amelinium.app

added in 1.0.0

amelinium service, application.

*local-config*

dynamic

A local configuration file in EDN format which will be loaded after all other configuration files so its entries will replace any existing entries during merge. Be aware that meta-merge is used in the process so values of nested maps are replaced not the whole branches. Used when amelinium.app/configure! is called. Please be aware that using this setting to override settings in certain environments may be considered less elastic than creating a separate, local folder and putting local configuration files there.

*local-dev-config*

dynamic

Much like amelinium.app/*local-config* but used when amelinium.app/configure-dev! is called. Please be aware that using this setting (and calling amelinium.app/configure-dev!) to work in development environment may be considered less elastic than creating a separate, local folder for development configuration and changing the application profile property there. See also amelinium.app/start-dev! and amelinium.app/configure-dev!.

*ns-reload-watch-dirs*

dynamic

A sequence of directories to be watched when reloading code. Used by amelinium.app/reload-namespaces and (indirectly) by amelinium.app/reload! and amelinium.app/make-ns-tracker. Can also be set using amelinium.app/with-watch-dirs.

*ns-tracker*

dynamic

Instance of ns-tracker used to track directories for code changes. By default it is initialized by calling ns-tracker.core/ns-tracker (from amelinium.app/make-ns-tracker) with a sequence of directories from amelinium.app/*ns-reload-watch-dirs*.

*resource-admin-dirs*

dynamic

The same as amelinium.app/*resource-config-dirs* but loaded when application is run in administrative mode (and configured with amelinium.app/configure-admin!).

Regular config directories (from amelinium.app/*resource-config-dirs*) are not scanned nor loaded. This is useful when performing serious administrative tasks (like database migrations) requiring different or additional setup (e.g. specially configured data sources with different credentials used to create database connections). See also amelinium.app/start-admin! and amelinium.app/configure-admin!.

*resource-config-dirs*

dynamic

A sequence of paths (relative to the resources directory) to be scanned for EDN configuration files. Loaded in the same order as they appear and used by amelinium.app/configure! and amelinium.app/configure-dev!.

Please note that when building your own instance of application you still may refer to the original Amelinium configs since resource directories are shared across loaded libraries. Therefore, it is possible to load original files (for instance some basic translations) and override some of them in your i18n configuration. See also amelinium.app/start! and amelinium.app/configure!.

-main

(-main)

config

A nested map containing application configuration which was read from files.

configure!

(configure!)

Configures the application. Calls amelinium.app/configure-app passing values of amelinium.app/*local-config* and amelinium.app/*resource-config-dirs*. See also amelinium.app/start!.

configure-admin!

(configure-admin!)

Configures the application in administrative mode. Calls amelinium.app/configure-app passing it values of amelinium.app/*local-config* and amelinium.app/*resource-admin-dirs*. See also amelinium.app/start-admin!.

configure-app

(configure-app)(configure-app local-config-file rc-dirs & keys)

Configures the application using local-config-file and rc-dirs (list of relative paths to be scanned for EDN files with configuration maps to be merged with meta-merge).

Uses amelinium.system/read-configs to load EDN files and merge them, and then sets the global variable amelinium.app/config to contain it. The next step is to call amelinium.system/prep and update the global variable amelinium.app/post-config with its result.

If keys are given then amelinium.system/config is only updated when it does not yet have a truthy value, and after that the amelinium.system/prep is called with keys passed to only prepare values for the specified keys. The result of this call is stored in amelinium.app/post-config.

The function returns :configured keyword. See also amelinium.app/configure!.

configure-dev!

(configure-dev!)

Configures the application in development mode. Calls amelinium.app/configure-app passing it values of amelinium.app/*local-dev-config* and amelinium.app/*resource-config-dirs*. Please be aware that using this to work in development environment may be considered less elastic than creating a separate, local folder for development configuration and changing the application profile property there (a map identified with :amelinium.app/properties key and its :profile key). See also amelinium.app/start-dev!.

configured?

(configured?)

Returns true when application is configured.

cprint-config

(cprint-config)

Prints current configuration (not parsed) of application using cprint.

cprint-post-config

(cprint-post-config)

Prints current, pre-parsed configuration of application using cprint.

cprint-state

(cprint-state)

Prints current state of application using cprint.

exception

Unhandled exception object thrown during starting, stopping or suspending.

expand-app

(expand-app & keys)

failed?

(failed?)

Returns true when application is in failed phase.

make-ns-tracker

(make-ns-tracker)

Creates ns-tracker instance for tracking code changes in directories specified with amelinium.app/*ns-reload-watch-dirs*.

phase

A keyword describing current phase (:stopping, :stoppped, :starting, :running, :suspended, :suspending, :resuming, :failed).

post-config

A nested map containing application configuration which was pre-parsed.

print-config

(print-config)

Prints current configuration (not parsed) of application.

print-post-config

(print-post-config)

Prints current, pre-parsed configuration of application.

print-state

(print-state)

Prints current state of application.

reload!

(reload! & k)

When the application is stopped, reloads code (using amelinium.app/reload-namespaces). Otherwise stops the application, reloads namespaces and starts it again.

reload-namespaces

(reload-namespaces)

Reloads code (using clojure.core/require with :reload flag) in namespaces found in files listed in amelinium.app/*ns-reload-watch-dirs*.

restart!

(restart! & k)

Restarts the application. Calls amelinium.app/stop-app (passing it optional keys identifying components which should be stopped) and the calls amelinium.app/start-app passing values of amelinium.app/*local-config*, amelinium.app/*resource-config-dirs* and optional keys identifying components which should be started. If no components are given then only those which were previously started are stopped and all are started. Application configuration is re-initialized during the process.

resume!

(resume! & k)

Resumes the application which was previously suspended. Calls amelinium.app/resume-app passing it optional keys identifying components which should be resumed. If no components are given then only those which were previously suspended are resumed.

resume-app

(resume-app & keys)

resuming?

(resuming?)

Returns true when application is in resuming phase.

running?

(running?)

Returns true when application is in running phase.

start!

(start! & k)

Starts or resumes the application. Calls amelinium.app/start-app passing values of amelinium.app/*local-config*, amelinium.app/*resource-config-dirs* and optional keys identifying components which should be configured and started. If no components are given, all are started. If the application is in suspended state, it is resumed (see amelinium.app/resume!).

start-admin!

(start-admin! & k)

Starts or resumes the application using administrative configuration. Calls amelinium.app/start-app passing values of amelinium.app/*local-config*, amelinium.app/*resource-admin-dirs* and optional keys identifying components which should be configured and started. If no components are given, all are started. If the application is in suspended state, it is resumed (see amelinium.app/resume!).

This mode is intended to be used when performing administrative tasks (like database migrations) requiring different or additional setup (e.g. specially configured data sources with different credentials used to create database connections).

start-app

(start-app)(start-app local-config-file rc-dirs & keys)

start-dev!

(start-dev! & k)

Starts or resumes the application using development configuration. Calls amelinium.app/start-app passing values of amelinium.app/*local-dev-config*, amelinium.app/*resource-config-dirs* and optional keys identifying components which should be configured and started. If no components are given, all are started. If the application is in suspended state, it is resumed (see amelinium.app/resume!).

Please be aware that using this to work in development environment may be considered less elastic than creating a separate, local folder for development configuration and changing the application profile property there (a map identified with :amelinium.app/properties key and its :profile key).

starting?

(starting?)

Returns true when application is in starting phase.

state

A nested map containing current state of application when it is running.

state-from-exception

(state-from-exception ex)

Takes an exception object and sets the global variable amelinium.app/state to contain the exception data extracted from it. Additionally sets the current value of global variable amelinium.app/phase to :failed and uses logging to notify about this event (with the log level set to error).

stop!

(stop! & k)

Stops the application. Calls amelinium.app/stop-app passing it optional keys identifying components which should be stopped. If no components are given then only those which were previously started are stopped. After successful stop, application configuration is removed.

stop-app

(stop-app & keys)

stopped?

(stopped?)

Returns true when application is in stopped phase.

stopping?

(stopping?)

Returns true when application is in stopping phase.

suspend!

(suspend! & k)

Suspends the application. Calls amelinium.app/suspend-app passing it optional keys identifying components which should be suspended. If no components are given then only those which were previously started are suspended.

suspend-app

(suspend-app & keys)

suspended?

(suspended?)

Returns true when application is in suspended phase.

suspending?

(suspending?)

Returns true when application is in suspending phase.

with-config-dirs

macro

(with-config-dirs dirs & body)

Sets the dynamic variable amelinium.app/*resource-config-dirs* and executes body.

with-configs

macro

(with-configs local-file dirs admin-dirs & body)

Sets the dynamic variables amelinium.app/*resource-config-dirs*, amelinium.app/*resource-admin-dirs* and amelinium.app/*local-config* to the given values and executes body. May be helpful in overriding defaults when instantiating app.clj and creating custom wrappers around common management functions (like amelinium.app/start!, amelinium.app/stop!, amelinium.app/reload! and others).

with-local-config

macro

(with-local-config local-file & body)

Sets the dynamic variable amelinium.app/*local-config* and executes body.

with-ns-tracker

macro

(with-ns-tracker ns-tracker & body)

Sets amelinium.app/*ns-tracker* to the given value and executes body. Helpful when creating custom amelinium.app/reload! function in instantiated app.clj.

with-watch-dirs

macro

(with-watch-dirs watch-dirs & body)

Sets the dynamic variable amelinium.app/*ns-reload-watch-dirs* to the given value and executes body. May be helpful when creating custom namespace tracker (and setting amelinium.app/*ns-tracker* value) in instantiated app.clj.