Package io.higson.runtime.core

Class HigsonEngineFactory

java.lang.Object
io.higson.runtime.core.HigsonEngineFactory
public class HigsonEngineFactory extends Object
This class is very important aspect of higson-runtime configuration. Main responsibility of this class is to create instance of HigsonEngineImpl using create(), that is used in many places during application runtime. Using this factory, developers might have impact on some behaviour of the runtime. It will be described below.

The most important aspect of configuration is to setup dataSource, so this is main action for developer to take. More configuration options are available via flags and setter's. During engine creation, multiple things happens:
1. Watchers are created by default, since autoStartWatchers is set to true
2. Database access points (DAO's) and providers for core elements like functions, parameters, domain are created.
3. Interceptors/listeners might be injected to the engine.
4. Functions invokers supported by higson are created.


There is also possibility for using higson engine in developer mode. By enabling developer mode setDeveloperMode(boolean) to true, and setting userName setUsername(String), runtime will be aware of user perspective(higson session) automatically. For example, if user is making some changes in parameters/function/domain via Higson Studio connected to the same dataSource as runtime, but doesn't want to public the session (so other users can't see it) and his runtime environment will be aware of this change. If developer mode is set to [@code false}, then user in higson studio has to manually publish his session, so any changes done to parameters, functions or domain will be available via higson runtime.


Sample basic configuration: 

  DataSource ds = ... //
  HigsonEngineFactory factory = new HigsonEngineFactory(ds);
  factory.create();
Sample configuration with developer mode ON for username "jason": 

  DataSource ds = ... //
  HigsonEngineFactory factory = new HigsonEngineFactory(ds);
  factory.setDeveloperMode(true);
  factory.setUsername("jason");
  factory.create();

  • Constructor Details

  • Method Details

    • setHigsonDataSource

      public void setHigsonDataSource(HigsonDataSource higsonDataSource)

    • setDataSource

      public final void setDataSource(DataSource dataSource)

    • setDataSource

      public final void setDataSource(HigsonDataSource dataSource)
      This method setup dataSource used by higson-runtime with all required elements, like: main access points to parameters, functions, external sources, domain, etc. If developer didn't provided any connection interceptor, then StdConnectionInterceptor will be used.
      Parameters:
      dataSource - that will be used during runtime

    • setValueNeverNull

      public void setValueNeverNull(boolean valueNeverNull)
      Flag responsible for managing global support of nullable parameters results by engine. If it is set to true (by default), then parameters will never return null, but instead they will return instance of EmptyParamValue.
      Parameters:
      valueNeverNull - true of false to be set

    • setMaxConcurrentLoads

      public void setMaxConcurrentLoads(int maxConcurrentLoads)
      Sets limited access to concurrent loads of parameters. Default value is 3. This helps to control usage of resources, since fetching parameters might be very stressful for the application.
      Parameters:
      maxConcurrentLoads - currentLoads maximal number of concurrent loads

    • setSessionProvider

      public void setSessionProvider(MpUserSessionProvider sessionProvider)
      Sets session provider, which holds information about a user like userName.
      Parameters:
      sessionProvider - instance of MpUserSessionProvider

    • setAutoStartWatchers

      public void setAutoStartWatchers(boolean autoStartWatchers)
      Control flag for starting watchers during engine build. true by default.
      Parameters:
      autoStartWatchers - if true, during engine creation watchers will be created. If false, then nothing will happen.

    • setRhinoPlugins

      @Deprecated public void setRhinoPlugins(Map<String,Object> rhinoPlugins)
      Deprecated.
      - This method will be removed in the future. Please use according setCustomPlugins(Map).
      Parameters:
      rhinoPlugins - Custom plugins, that will be added to the base of higson supported plugins.

    • setCustomPlugins

      public void setCustomPlugins(Map<String,Object> customPlugins)
      This method allows developers to inject custom plugins or even override behaviour of higson plugins. Plugins will be added, when method create() is called. Higson supported plugins codes:
      • log
      • date
      • ctx
      • domain
      • util
      Parameters:
      customPlugins - map, where key is plugin code, value is instance of the plugin

    • setParamsToPrefetch

      public void setParamsToPrefetch(List<String> paramsToPrefetch)
      Allows to setup a list of parameters codes to be fetched early on system startup.
      Parameters:
      paramsToPrefetch - list of parameters codes

    • setFunctionsToPrefetch

      public void setFunctionsToPrefetch(List<String> functionsToPrefetch)
      Allows to setup a list of functions codes to be fetched early on system startup.
      Parameters:
      functionsToPrefetch - list of functions codes

    • addRegionForParametersPrefetch

      public void addRegionForParametersPrefetch(String profileCode, String regionCode)
      Allows specifying region code within profile, which is used to fetch parameters early on system startup. Bear in mind that adding too many profileCodes or regionCodes for given profileCode puts a lot of pressure on the database on system startup.
      Parameters:
      profileCode - profile code
      regionCode - region code

    • create

      public HigsonEngineImpl create()
      Creates HigsonEngine instance based on given configuration. Here multiple whole structure of an engine is created. First the dialect for database is registered. After that, all providers and invokers for parameters, functions, etc. All supported types for HigsonContext are created here as well. ParamEngineConfigBuilder is used as well to build ParamEngineConfig.

      autoStartWatchers if it is set to true (by default it is), then all watchers for higson main functionalities will be enabled.

      enableDomainCache if it is set to true (by default it is), then domain will be cached and maintained by higson-runtime.

      paramsToPrefetch and functionsToPrefetch gives a possibility to early fetch on startup list of given parameters or functions codes.

      Returns:
      new higson engine
      Throws:
      HigsonRuntimeException - if dataSource is null

    • startParamWatcher

      public ParamRuntimeWatcher startParamWatcher(WatcherConfig config)
      Creates, inject watcher event listener and starts parameters runtime watcher.
      Parameters:
      config - for watcher
      Returns:
      instance of started runtime watcher
      See Also:

    • startFunctionWatcher

      public FunctionRuntimeWatcher startFunctionWatcher(WatcherConfig config)
      Creates, inject watcher event listener and starts functions runtime watcher.
      Parameters:
      config - for watcher
      Returns:
      instance of started runtime watcher
      See Also:

    • startVersionWatcher

      public VersionRuntimeWatcher startVersionWatcher(WatcherConfig config)
      Creates and starts version runtime watcher.
      Parameters:
      config - for watcher
      Returns:
      instance of started runtime watcher
      See Also:

    • createVersionWatcher

      public VersionRuntimeWatcher createVersionWatcher(WatcherConfig config)

    • createUserRegionVersionWatcher

      public UserRegionVersionRuntimeWatcher createUserRegionVersionWatcher(WatcherConfig config)

    • startScheduleWatcher

      public ScheduleRuntimeWatcher startScheduleWatcher()
      Creates and starts schedule runtime watcher. WatcherConfig is using property set via #scheduleWatcherPauseSeconds.
      Returns:
      instance of started runtime watcher
      See Also:

    • startRefreshWatcher

      public RefreshRuntimeWatcher startRefreshWatcher(WatcherConfig config)
      Creates and starts refresh runtime watcher, that is responsible for evicting parameters from cache.
      Parameters:
      config - for watcher
      Returns:
      instance of started runtime watcher
      See Also:

    • startDomainWatcher

      public DomainRuntimeWatcher startDomainWatcher(WatcherConfig watcherConf)
      Creates and starts domain runtime watcher, if flag enableDomainCache is true.
      Parameters:
      watcherConf - for watcher
      Returns:
      instance of started runtime watcher
      See Also:

    • destroy

      public void destroy()
      This method stops all threads created by higson-runtime. All threads have to be stopped so that the JVM process can exit. This is very important to call this method from client application, otherwise the JVM will not stop. Below is the recommended way to free resources: 
         HigsonEngineFactory factory;
   HigsonEngine engine;

   [PostConstruct]
   public void init() {
     factory = new HigsonEngineFactory(dataSource);
     engine = factory.create();
   }

   [PreDestroy]
   public void destroy() {
     factory.destroy();
   }

    • setLevelCreatorInterceptor

      public void setLevelCreatorInterceptor(FunctionInvokerInterceptor levelCreatorInterceptor)
      Setup level creator interceptor. Higson provides default implementation if not specified.
      Parameters:
      levelCreatorInterceptor - acts as function invoker interceptor

    • setEnableDomainCache

      @Deprecated(forRemoval=true) public void setEnableDomainCache(boolean enableDomainCache)
      Deprecated, for removal: This API element is subject to removal in a future version.

    • setAttributeInterceptor

      public void setAttributeInterceptor(AttributeInterceptor attributeInterceptor)
      Setup attribute interceptor for attribute value provider.
      Parameters:
      attributeInterceptor - custom interceptor for domain attributes
      See Also:

    • setWatcherEventListener

      public void setWatcherEventListener(WatcherEventListener watcherEventListener)
      Setup watcher event listener for function and parameters runtime watchers.
      Parameters:
      watcherEventListener - custom event listener

    • isDeveloperMode

      public boolean isDeveloperMode()
      Checks if developerMode is ON or OFF.
      Returns:
      true if ON, false otherwise

    • setDeveloperMode

      public void setDeveloperMode(boolean developerMode)
      Setup higson engine with developer mode. It will change default behaviour of an engine. Default value is false.
      Parameters:
      developerMode - control flag

    • setUsername

      public void setUsername(String username)
      Setup username for developer mode.
      Parameters:
      username - to be used

    • setValidateFunctionArgumentsDataTypes

      public void setValidateFunctionArgumentsDataTypes(boolean validateFunctionArgumentsDataTypes)
      Setup built-in argument data types validator for function invocation. Default value is false.
      Parameters:
      validateFunctionArgumentsDataTypes - control flag

    • getPythonFunctionInvoker

      public Optional<PythonFunctionInvoker> getPythonFunctionInvoker()

    • addExternalDataSources

      public void addExternalDataSources(Map<String,DataSource> dataSourceMap)
      Same as setExternalDataSources(Map) and it will iterate over given map and call addExternalDataSource(String, DataSource)
      Parameters:
      dataSourceMap - of datasource and theirs codes

    • addExternalDataSource

      public void addExternalDataSource(String code, DataSource dataSource)
      Add external dataSource under given code, so higson will recognize it, when fetching for parameters that have defined this external source.
      Parameters:
      code - under which dataSource will be available
      dataSource - external dataSource

    • setExternalDataSources

      public void setExternalDataSources(Map<String,DataSource> map)
      Same as addExternalDataSources(Map) and it will iterate over given map and call addExternalDataSource(String, DataSource)
      Parameters:
      map - of datasource and theirs codes

    • redefineDomainCache

      public void redefineDomainCache(DomainCache newMpDomainCache, MpDomainCacheProvider newDomainCacheProvider, DomainCacheManager newDomainCacheManager)
      Setup custom domain cache, provider and manager for it. If developer provider custom implementations, then during create() higson will skip building them on its own.
      Parameters:
      newMpDomainCache - custom domain cache
      newDomainCacheProvider - custom domain cache provider
      newDomainCacheManager - custom domain cache manager

    • setExternalModulesForPython

      public void setExternalModulesForPython(List<String> modules)

    • setThrowOnNormalizeInputValueException

      public void setThrowOnNormalizeInputValueException(boolean throwOnNormalizeInputValueException)

    • addFunctionInvocationInterceptor

      public void addFunctionInvocationInterceptor(FunctionInvocationInterceptor functionInvocationInterceptor)
      Add user defined function invocation interceptor. Higson triggers added interceptor before every function invocation.
      Parameters:
      functionInvocationInterceptor - User defined function invocation interceptor
      See Also:

    • setFunctionLogLevelCacheTTL

      public void setFunctionLogLevelCacheTTL(Duration ttl)
      Set time-to-live (TTL) for function log level cached entries.

    • attachLogListener

      public void attachLogListener(LogListener logListener)

    • setIdleChecker

      public void setIdleChecker(IdleChecker idleChecker)

    • setMaxIdleTime

      public void setMaxIdleTime(Duration maxIdleTime)

    • setReloadPolicy

      public void setReloadPolicy(ReloadPolicy reloadPolicy)

    • getWatcherStartDelaySeconds

      @Deprecated(forRemoval=true) public int getWatcherStartDelaySeconds()
      Deprecated, for removal: This API element is subject to removal in a future version.

      Use watchersConfig and getStartDelaySeconds() of selected watcher

      Returns:
      watcher start delay in seconds of watchersConfig.paramWatcherConfig

    • getWatcherPauseSeconds

      @Deprecated(forRemoval=true) public int getWatcherPauseSeconds()
      Deprecated, for removal: This API element is subject to removal in a future version.

      Use watchersConfig and getWatcherPauseSeconds of selected watcher

      Returns:
      pause of watchers in seconds of watchersConfig.paramWatcherConfig

    • getWatcherErrorPauseSeconds

      @Deprecated(forRemoval=true) public int getWatcherErrorPauseSeconds()
      Deprecated, for removal: This API element is subject to removal in a future version.

      Use watchersConfig and getErrorPauseSeconds() of selected watcher

      Returns:
      pause during some error of watchers in seconds of watchersConfig.paramWatcherConfig

    • getScheduleWatcherPauseSeconds

      @Deprecated(forRemoval=true) public int getScheduleWatcherPauseSeconds()
      Deprecated, for removal: This API element is subject to removal in a future version.

      Use watchersConfig and getWatcherPauseSeconds() from scheduleRuntimeWatcherConfig

      Returns:
      pause in seconds of global schedule watcher

    • getRefreshWatcherConfig

      @Deprecated(forRemoval=true) public WatcherConfig getRefreshWatcherConfig()
      Deprecated, for removal: This API element is subject to removal in a future version.

      Use watchersConfig and getRefreshWatcherConfig() instead

      Returns:
      configuration of refresh watcher

    • getParamWatcherConfig

      @Deprecated(forRemoval=true) public WatcherConfig getParamWatcherConfig()
      Deprecated, for removal: This API element is subject to removal in a future version.

      Use watchersConfig and getParamWatcherConfig() instead

      Returns:
      configuration of parameters watcher

    • getFunctionWatcherConfig

      @Deprecated(forRemoval=true) public WatcherConfig getFunctionWatcherConfig()
      Deprecated, for removal: This API element is subject to removal in a future version.

      Use watchersConfig and getFunctionWatcherConfig() instead

      Returns:
      configuration of functions watcher

    • setWatcherStartDelaySeconds

      @Deprecated(forRemoval=true) public void setWatcherStartDelaySeconds(int watcherStartDelaySeconds)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use watchersConfig and set delay on any of selected watchers
      Setup delay of watchers in seconds. Default value is set to WatchersConfig.WATCHER_DEFAULT_START_DELAY seconds. Parameter and function watchers will have the same delay.
      Parameters:
      watcherStartDelaySeconds - delay in seconds

    • setWatcherPauseSeconds

      @Deprecated(forRemoval=true) public void setWatcherPauseSeconds(int watcherPauseSeconds)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use watchersConfig and set pause() on any of selected watchers
      Setup pause of watchers in seconds. Default value is set to WatchersConfig.WATCHER_DEFAULT_PAUSE seconds. Parameter and function watchers will have the same pause.
      Parameters:
      watcherPauseSeconds - pause in seconds

    • setWatcherErrorPauseSeconds

      @Deprecated(forRemoval=true) public void setWatcherErrorPauseSeconds(int watcherErrorPauseSeconds)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use watchersConfig and set error() on any of selected watchers
      Setup pause during some error of watchers in seconds. Default value is set to WatchersConfig.WATCHER_DEFAULT_RECOVERY seconds. Parameter and function watchers will have the same pause.
      Parameters:
      watcherErrorPauseSeconds - error pause in seconds

    • setWatcherForceSyncSeconds

      @Deprecated(forRemoval=true) public void setWatcherForceSyncSeconds(int seconds)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use watchersConfig and set force() on paramWatcherConfig
      Set the time after which the watcher will force a full cache synchronization. Currently only the param watcher supports this setting.
      Parameters:
      seconds - force sync pause in seconds

    • setRefreshWatcherConfig

      @Deprecated(forRemoval=true) public void setRefreshWatcherConfig(WatcherConfig conf)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use watchersConfig and set refreshWatcherConfig
      Sets the refresh watcher configuration (delay, pause, error pause)

    • setDomainWatcherInvalidateCacheTime

      @Deprecated(forRemoval=true) public void setDomainWatcherInvalidateCacheTime(int domainWatcherInvalidateCacheTime, TemporalUnit unit)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use watchersConfig and set invalidate on domainWatcherConfig
      Setup lifespan of domain trees in cache, if there are not used. By default domain tree will be removed from cache, if it's last build exceeds WatchersConfig.DOMAIN_WATCHER_INVALIDATE_TIME WatchersConfig.DOMAIN_WATCHER_INVALIDATE_TIME_UNIT (or any time defined by this method).
      Parameters:
      domainWatcherInvalidateCacheTime - value of lifespan. By default it will be WatchersConfig.DOMAIN_WATCHER_INVALIDATE_TIME
      unit - used with value from lifespan. By default it will be WatchersConfig.DOMAIN_WATCHER_INVALIDATE_TIME_UNIT

    • setScheduleWatcherPauseSeconds

      @Deprecated(forRemoval=true) public void setScheduleWatcherPauseSeconds(int scheduleWatcherPauseSeconds)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use watchersConfig and set pause() of scheduleRuntimeWatcherConfig
      Setup pause in seconds of global schedule watcher. Default value is set to WatchersConfig.SCHEDULE_WATCHER_DEFAULT_PAUSE seconds.
      Parameters:
      scheduleWatcherPauseSeconds - value of pause seconds