core.md

Core

The core is the heart and brain of this library. It controls all stages of the application in 4 major steps.

Summary

• Decorator @Application and Core
• Core States
• Step: Before Initialization
• Step: Initialization
• Step: After Initialization
• Step: Destruction
• Method: static createCore
• Method: static destroy
• Method: static getConstructors
• Method: static getCoreState
• Method: static getError
• Method: static getDependenciesTree
• Method: static getInstanceByName
• Method: static getInstances
• Method: static getOverrides
• Method: static getPropertiesHandler
• Method: static isDestroyed
• Method: static registerConfiguration
• Method: static registerCoreComponent
• Method: static registerInjection
• Method: static registerRest
• Method: static registerRestPath
• Method: static registerService
• Method: static setError
• Method: static whenBeforeInitializationIsDone
• Method: static whenDestroyed
• Method: static whenReady
• Method: static watchState

Decorator @Application and Core

The @Application and TheWayApplication are primordial to use this library. When a CoreInstance is created, the initialization step will initialize. The Core steps will be described in the subsequent sections.

A CoreInstance is created when:

• A class decorated with @Application with no parameters or with the parameter automatic = true and extends the class TheWayApplication
• A class decorated with @Application with the parameter automatic = false, is extended with TheWayApplication and the new is called

So, it's automatic or manually called.

Automatic: @Application with no parameters and a class extended with TheWayApplication class

import { Application, TheWayApplication } from '@umberware/the-way';

@Application()
export class Main extends TheWayApplication {}

The above example, the application will start automatically

Manually: @Application with parameter automatic with the value false, and a class extended with TheWayApplication class

import { Application, TheWayApplication } from '@umberware/the-way';

@Application(false)
export class Main extends TheWayApplication {}

...

 new Main();

In the example above, the application will start when the main class is created

Core States

The Core has a method that return an Observable from rxjs and this observable will return via .subscribe the current CoreState of the Core. When the Core State change, the observable will emit this new value. The values of this observable/CoreState has the type CoreStateEnum and the Core first state is WAITING

Step: Before Initialization

This is the first step and is activated when the Core Instance is created.

Is responsible for:

• Read the application.properties.yml with PropertiesHandler
• Create RegisterHandler and prepare to register paths, classes and others
• Create DependencyHandler to build the dependencies tree
• Create InstanceHandler to build the instances
• Create FileHandler to scan the folders(of your project) and import these classes decorated with Application Components Decorators. This FileHandler will be changed in future release to compose the build process(will be handled in "The Way CI") and not the running process with the Core.

When Started:

• CoreState change: From WAITING to BEFORE_INITIALIZATION_STARTED

When Finished:

• CoreState change: From BEFORE_INITIALIZATION_STARTED to BEFORE_INITIALIZATION_DONE
• The PropertiesHandler can be injected, retrieved with getInstanceByName or getPropertiesHandler

Step: Initialization

This is the second step and is activated when the current value of the CoreState is BEFORE_INITIALIZATION_DONE.

Is responsible for:

• Build the Dependencies Tree
• All registered classes decorated with @Configuration and extended with Configurable will be Configured
• All registered classes via Application Components Decorators and Register Handler will be built
• When the server is enabled, the Server Configuration will be configured and the registered paths with the Rest Decorators will be bind.

When Started:

• CoreState change: from BEFORE_INITIALIZATION_DONE to INITIALIZATION_STARTED

When Finished:

• CoreState change: from INITIALIZATION_STARTED to INITIALIZATION_DONE
• All classes mapped with the Application Components Decorators, can be Injected
• All classes decorated with @Configuration and is extended with Configurable, are configured
• All classes that are extended with Destroyable, will be destroyed when the Core step change to destruction
• When server is enabled, the Http and/or Https can be accessed, and the rest operations is bind and accessible.

Step: After Initialization

This is the second step and is activated when the current value of the CoreState is INITIALIZATION_DONE.

Is responsible for:

• Mark the CoreState as READY

When Finished:

• CoreState change: from INITIALIZATION_DONE to READY

Step: Destruction

This is the destruction step and is activated when is called the method destroy() or occurs an error in the initialization steps.

Is responsible for:

• Destroy the core
• Destroy all classes instances that extends the destroyable class
• Will terminate the node process if the property the-way.core.process-exit is true (see properties)

When Started:

• CoreState change: from Any Core State to DESTRUCTION_STARTED

When Finished:

• CoreState change: from DESTRUCTION_STARTED to DESTRUCTION_DONE

Method: static createCore

This method is called in @Application or in TheWayApplication Constructor. This method tell to the CORE to initialize the application.

Params

• application: Can be a Class or Instance of a class. This parameter will be used to set the application instance. After the initialization, the method start of TheWayApplication will be called.

Method: static destroy

This method can be called in any stage of the Core. When called, the Core will start the process to destroy the instances, configurations and connections.

Return

• Returns an observable that will emit value when the construction step is done, or an error occurs in the destruction step

Method: static getConstructors

This method will access the register handler and get all the constructions registered

Return

• Returns all registered constructors: ConstructorMapModel

Method: static getCoreState

Retrieves the current Core State

Return

• Actual state: CoreStateEnum

Method: static getError

This method will return the error if an error occurred or was set

Return

• The Error

Method: static getDependenciesTree

Retrieves the dependencies tree of the application

Return

• The built dependencies tree: DependencyTreeModel

Method: static getInstanceByName

Retrieve the class singleton by name class

Params

• name: The class name

Throws:

• ApplicationException: If the wanted instance is not found

Return

• The instance of the class: T

Method: static getInstances

Retrieve all instances

Return

• An array of the instances

Method: static getOverrides

Retrieve all overridden classes

Return

• The overridden map: OverriddenMapModel

Method: static getPropertiesHandler

Will return the PropertiesHandler of the application

Return

• The propertiesHandler: PropertiesHandler

Method: static isDestroyed

Will check if the core is destroyed

Return

• A boolean, that will be true when the Core is destroyed

Method: static registerConfiguration

This method will register a class decorated with @Configuration. For Core use only

Params

• configurationConstructor: The decorated class
• over The class that must be overridden. It is optional

Method: static registerCoreComponent

This method will register a core component. For Core use only

Params

• componentConstructor: The Core Component class

Method: static registerInjection

This method will register a dependency and map injection point

Params

• dependencyConstructor: The dependency class
• source: The dependent class
• propertyKey: The dependent class injection point

Method: static registerRest

This is method is used to register a class decorated with @Rest

Params

• restConstructor: Is the class decorated with @Rest
• path: The father path. All method decorated with Rest Decorators will inherit this path
• authenticated: When true, all inherit paths need a user signed in
• allowedProfiles: Is the allowed profiles that can execute the operations mapped in the methods decorated with some rest decorator

Method: static registerRestPath

This is method is used to register a REST operation in methods decorated with some Rest Decorators

Params

• httpType: Is the HttpTypeEnum (Get, Post, Delete, ...)
• path: Is the operation PATH
• target: Is the method class
• methodName: Is the method name
• authenticated: When true, the mapped operation will be executed only if has a user authenticated
• allowedProfiles: Is the allowed profiles that can execute the operation

Method: static registerService

This method will register a class decorated with ´@Service. For Core use only

Params

• serviceConstructor: The decorated class
• over The class that must be overridden. It is optional

Method: static setError

When this method is called, the destruction step will start, and the ERROR will be registered

Param:

• error: Is the error that will be registered in the core

Method: static whenBeforeInitializationIsDone

This method return an observable that will emit value when the core assumes the state of BEFORE_INITIALIZATION_DONE

Return

• Observable

Method: static whenDestroyed

This method return an observable that will emit value when the core assumes the state of DESTRUCTION_DONE

Return

• Observable

Method: static whenReady

This method return an observable that will emit value when the core assumes the state of READY

Return

• Observable

Method: static watchState

This method will return an observable that will emit every change of the core state

Return

• Observable