Package sirius.kernel

Provides the main setup classes for the SIRIUS kernel.

See: Description

Interface Summary

Interface	Description
Killable	Classes implementing this interface get notified once the framework is being shut down.
Startable	Classes implementing this interface get notified once the framework is started.
Stoppable	Classes implementing this interface get notified once the framework is being shut down.

Class Summary

Class	Description
Classpath	Retrieves a filtered list of resources in the classpath.
DockerHelper	Initializes Docker Composer if requested by the framework.
Setup	Used to configure the setup of the SIRIUS framework.
Sirius	Loads and initializes the framework.

Enum Summary

Enum	Description
Setup.Mode	Determines the mode in which the framework should run.

Package sirius.kernel Description

Provides the main setup classes for the SIRIUS kernel.

In order to start and stop the SIRIUS framework, Sirius.start(sirius.kernel.Setup) and Sirius.stop() can be invoked. Setup can be subclassed to provide further tweaking of the framework behaviour.

The Classpath is responsible for discovering all classes and resources within the classpath of the application. It will scan all classpath roots which contain a component.marker file.

Discovery Based Programming

The whole SIRIUS framework ist built around the concept of Discovery Based Programming. Therefore many components don't actively call other services but rather implement an interface. This is discovered at runtime and the appropriate service is activated.

An example is the Timers which calls components in regular intervals. In order to use this service, an appropriate interface like EveryMinute has be implemented. Everything else is take care of be the framework.

In order to support discovery for an implementation the class has to wear a Register annotation. To provide your own services utilizing discovery, fields can be annotated with Parts which is then automatically filled with all components implementing the given interface.

Note that the Part/Register mechanism can also be used for classic Dependency Injection (Filling a single dependency at runtime just referring to it by an interface.)

Also note that the annotations Part, Parts and Register are itself extensions to the IoC (inversion of control) micro kernel (see sirius.kernel.di.std). Therefore own annotations can be easily added.

System Configuration

Sirius provides a flexible way of building up a system configuration using the Typesafe Config Library. The config can be accessed in three ways. The raw configuration is available via Sirius.getSettings(). Also the annotation ConfigValue can be placed on a field of a registered component to automatically fill it with the appropriate config value.

Extensions provide a way to have several config files contribute to one section which is then consumed by a service. An example of this would be the CacheManager which permits to define caches used throughout the application. To declare the behaviour of a Cache an extension has to be placed in any config file which contributes to cache.[name]:

 
 cache {
    my-cache {
         maxSize = 100
         ttl = 1 hour
    }
 }
 
 

If a value is omitted the default value (in this case defined in component-kernel.conf) will be applied.

The order in which the configs are loaded is the following (can be customized by overriding Setup) - config files can always redefine values of their predecessors:

1. Each component-[module].conf found for a classpath root (detected via a component.marker)
2. application.conf (unless running as test)
3. develop.conf - if running in debug mode and not running as unit test
4. Each settings.conf for all active customizations (see below)
5. instance.conf - This file is not loaded from the classpath but form the local file system (where the app is started)

Using this layout, all default values can be declared in the appropriate component-[name].conf rather than be buried somewhere in the Java code. This makes maintaining and discovering them quite easy.

Frameworks

Sirius modules are split up into frameworks which can be dis- or enabled. The kernel module for example provides timer as a framework. So if an application does not require a timer service, this framework can be disabled by setting sirius.frameworks.kernel.timer = false. By default this the timer is active (see component-kernel.conf). To provide custom frameworks which can be dis- or enabled a default value has to be defined in the component-[name].conf). Then it can be used as Register.framework() in the appropriate components. If the framework is not enabled, these component will be ignored by SIRIUS.

Customizations

Often it is necessary to add or change the behaviour of an application for specific customers. In order to still keep the whole code in one code base (which permits refactorings etc.), SIRIUS supports customizations.

A customization is defined by putting all classes into a package named customizations.[name]. All resources for this customization have to be placed in the folder customizations/[name]. Now analog to frameworks the config property sirius.customizations - which is a list, so that several customizations can be active at once.

Now if a customization is active, all resources present override the default resources and all classes wearing a Register annotation are loaded. Note that a customization can even re-register and therefore replace a default component registered for the same type. Finally, the settings.conf within the customization is loaded (overriding application.conf, but not instance.conf).