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.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static enum	RunLevelController.ThreadingPolicy These are the policies for how the RunLevelController will use threads

Method Summary

Modifier and Type	Method and Description
public void	cancel() If there is a current procedure in process this method will get it and cancel it
public long	Returns: The amount of time in milliseconds that cancel will wait for running services 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
public RunLevelFuture	Returns: the current job the run level controller is working on or null if the system is not currently in flight 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
public int	Returns: the current run level, or null if no run level has been been achieved getCurrentRunLevel() The current run level state.
public Executor	Returns: The currently installed executor. Will not return null (the default executor implementation will be returned if the user has not supplied an executor) getExecutor() Gets the executor that will be used by the system when executing tasks.
public int	Returns: the current number of maximum useable threads getMaximumUseableThreads() Returns the current number of maximum useable threads
public RunLevelController.ThreadingPolicy	Returns: The threading policy currently in use with this controller getThreadingPolicy() Returns the threading policy currently being used by this controller
public Integer	Returns: null if there is no override or the value that the `RunLevel#mode()` value should be getValidationOverride() Returns the override value for the `RunLevel#mode()` field in RunLevel services.
public void	proceedTo(int The level that should be proceeded to runLevel) This method will move to the given run level synchronously as per `RunLevelController#proceedToAsync(int)`.
public RunLevelFuture	Returns: The future that can be used to wait for this object proceedToAsync(int the run level to move to runLevel) Causes this RunLevelController to move to the specified run level for all `RunLevel` instances, orchestrating the appropriate lifecycle events.
public void	setCancelTimeoutMilliseconds(long The amount of time in milliseconds that cancel will wait for running services. Must be greater than 0 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).
public void	setExecutor(Executor The executor to use for the next job. If null a default executor will be used executor) Sets the executor to use for the next job.
public void	setMaximumUseableThreads(int The maximum number of threads that can be used by the system for creation or destruction of services maximumThreads) This sets the maximum number of threads that the system can create for creation and/or destruction of threads.
public void	setThreadingPolicy(RunLevelController.ThreadingPolicy The policy that should be used by this controller policy) Sets the threading policy that will be used by this controller.
public void	setValidationOverride(Integer null if there is no override or the value that the `RunLevel#mode()` value should be validationMode) Sets the override value for the `RunLevel#mode()` field in RunLevel services.

Method Detail

cancel	back to summary
public void cancel() If there is a current procedure in process this method will get it and cancel it

getCancelTimeoutMilliseconds	back to summary
public 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:long The amount of time in milliseconds that cancel will wait for running services

getCancelTimeoutMilliseconds

back to summary

public 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:long: The amount of time in milliseconds that cancel will wait for running services

getCurrentProceeding	back to summary
public 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:RunLevelFuture the current job the run level controller is working on or null if the system is not currently in flight

getCurrentProceeding

back to summary

public 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:RunLevelFuture: the current job the run level controller is working on or null if the system is not currently in flight

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

getCurrentRunLevel

back to summary

public int getCurrentRunLevel()

The current run level state. This represents the last run level successfully achieved by the underlying RunLevelController responsible for this scope.

Returns:int: the current run level, or null if no run level has been been achieved

getExecutor	back to summary
public 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:Executor The currently installed executor. Will not return null (the default executor implementation will be returned if the user has not supplied an executor)

getExecutor

back to summary

public 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:Executor: The currently installed executor. Will not return null (the default executor implementation will be returned if the user has not supplied an executor)

getMaximumUseableThreads	back to summary
public int getMaximumUseableThreads() Returns the current number of maximum useable threads Returns:int the current number of maximum useable threads

getMaximumUseableThreads

back to summary

public int getMaximumUseableThreads()

Returns the current number of maximum useable threads

Returns:int: the current number of maximum useable threads

getThreadingPolicy	back to summary
public RunLevelController.ThreadingPolicy getThreadingPolicy() Returns the threading policy currently being used by this controller Returns:RunLevelController.ThreadingPolicy The threading policy currently in use with this controller

getThreadingPolicy

back to summary

public RunLevelController.ThreadingPolicy getThreadingPolicy()

Returns the threading policy currently being used by this controller

Returns:RunLevelController.ThreadingPolicy: The threading policy currently in use with this controller

getValidationOverride back to summary

getValidationOverride	back to summary
public 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:Integer null if there is no override or the value that the `RunLevel#mode()` value should be

public 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:Integer: null if there is no override or the value that the RunLevel#mode() value should be

proceedTo back to summary

proceedTo	back to summary
public void proceedTo(int runLevel) throws CurrentlyRunningException This method will move to the given run level synchronously as per `RunLevelController#proceedToAsync(int)`. Parameters runLevel:int The level that should be proceeded to Exceptions CurrentlyRunningException: if there is an already running job in progress

public void proceedTo(int runLevel) throws CurrentlyRunningException

This method will move to the given run level synchronously as per RunLevelController#proceedToAsync(int).

Parameters

runLevel:int: The level that should be proceeded to

Exceptions

CurrentlyRunningException:: if there is an already running job in progress

proceedToAsync back to summary

proceedToAsync	back to summary
public RunLevelFuture proceedToAsync(int runLevel) throws CurrentlyRunningException, 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:int the run level to move to Returns:RunLevelFuture The future that can be used to wait for this object Exceptions CurrentlyRunningException: if there is currently a job running this exception will be thrown with the currently running job IllegalStateException: if this method is called when the USE_NO_THREADS policy is in effect

public RunLevelFuture proceedToAsync(int runLevel) throws CurrentlyRunningException, 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:int: the run level to move to

Returns:RunLevelFuture

The future that can be used to wait for this object

Exceptions

CurrentlyRunningException:: if there is currently a job running this exception will be thrown with the currently running job
IllegalStateException:: if this method is called when the USE_NO_THREADS policy is in effect

setCancelTimeoutMilliseconds	back to summary
public 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:long The amount of time in milliseconds that cancel will wait for running services. Must be greater than 0

setCancelTimeoutMilliseconds

back to summary

public 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:long: The amount of time in milliseconds that cancel will wait for running services. Must be greater than 0

setExecutor	back to summary
public void setExecutor(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:Executor The executor to use for the next job. If null a default executor will be used

setExecutor

back to summary

public void setExecutor(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:Executor: The executor to use for the next job. If null a default executor will be used

setMaximumUseableThreads	back to summary
public 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:int The maximum number of threads that can be used by the system for creation or destruction of services

setMaximumUseableThreads

back to summary

public 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:int: The maximum number of threads that can be used by the system for creation or destruction of services

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

setThreadingPolicy

back to summary

public void setThreadingPolicy(RunLevelController.ThreadingPolicy policy)

Sets the threading policy that will be used by this controller. The values can be:

FULLY_THREADED: Use maximumUseableThreads to complete any task
USE_NO_THREADS: Never create a thread, use the callers thread always

Parameters

policy:RunLevelController.ThreadingPolicy: The policy that should be used by this controller

setValidationOverride back to summary

setValidationOverride	back to summary
public void setValidationOverride(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:Integer null if there is no override or the value that the `RunLevel#mode()` value should be

public void setValidationOverride(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:Integer: null if there is no override or the value that the RunLevel#mode() value should be

org.glassfish.hk2.runlevel back to summary

public final Enum RunLevelController.ThreadingPolicy

Class Inheritance

extends Enum<RunLevelController.ThreadingPolicy>

java.lang.Object
java.lang.Enum
org.glassfish.hk2.runlevel.RunLevelController.ThreadingPolicy

These are the policies for how the RunLevelController will use threads

Author: jwells

Field Summary

Modifier and Type	Field and Description
public static final RunLevelController.ThreadingPolicy	FULLY_THREADED The RunLevelController will use as many threads as it needs (but controlled by the MaximumUseableThreads value)
public static final RunLevelController.ThreadingPolicy	USE_NO_THREADS The RunLevelController will use a minimal number of threads.

Constructor Summary

Access	Constructor and Description
private	ThreadingPolicy()

Method Summary

Modifier and Type	Method and Description
public static RunLevelController.ThreadingPolicy	valueOf(String name)
public static RunLevelController.ThreadingPolicy[]	values()

Inherited from java.lang.Enum:: clone compareTo describeConstable equals finalize getDeclaringClass hashCode name ordinal toString valueOf

Field Detail

FULLY_THREADED	back to summary
public static final RunLevelController.ThreadingPolicy FULLY_THREADED The RunLevelController will use as many threads as it needs (but controlled by the MaximumUseableThreads value)

USE_NO_THREADS	back to summary
public static final RunLevelController.ThreadingPolicy USE_NO_THREADS The RunLevelController will use a minimal number of threads. However, some threads will still be used to support canceling jobs that have hung The MaximumUsealbeThreads value will be ignored, and only one extra thread will be used per non-hung proceedTo

Constructor Detail

ThreadingPolicy	back to summary
private ThreadingPolicy()

Method Detail

valueOf	back to summary
public static RunLevelController.ThreadingPolicy valueOf(String name)

values	back to summary
public static RunLevelController.ThreadingPolicy[] values()

public Interface RunLevelController

Nested and Inner Type Summary

Method Summary

Method Detail

public final Enum RunLevelController.ThreadingPolicy

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail