App


Overview

The Slate App is a base application and template to build console, batch, cli and server applications. It has pre-built support for common features such as command line args, environment selection, configs per environment, logging, life-cycle events, help text, diagnostics and much more. This is accomplished by integrating some of the components and utilities available in the Common project. You can create a app quickly using the Kiit command line executable with the following inputs. Also refer to the Example_App.kt.

    
    slatekit new app -name="SampleApp" -package="mycompany.apps"
    


Diagram

A high-level diagram of the concepts in this component



Goals

We often have to create a new application which requires typically much boiler-plate code. These include environments, config files, argument parsing, logging setup, and application life-cycle events. This component quickly gets a new application set up with all these features ready.



Goal Description
1. Template Provide template for any application ( Console, Batch, CLI, Server )
2. Features Provide pre-built support commandline args, config, logging, and more.
3. Standardized Provide standardized setup, functionality and diagnostics



Status

This component is currently stable and there is a project generator for it.

Feature Status Description
Docker Future Support for generating Docker images

Back to top



Install

Use the following settings in gradle for installing this component.

    repositories {
        // other repositories
        maven { url  "http://dl.bintray.com/codehelixinc/slatekit" }
    }

    dependencies {
        // other dependencies ...

        compile 'com.slatekit:slatekit-app:1.0.0'
    }

Back to top



Sources

Jar slatekit.app.jar
Package slatekit.app
Sources slatekit-app
Example Example_App.kt
Version
License
Requires See build.gradle for more info.

Back to top



Example

You can generate a sample app using the slatekit executable. Also refer to the Example_App.kt

    
    :> slatekit new app -name="MyApp1" -packageName="company1.myapp1"
    

Back to top



Concepts

Concept Description
1. Life-cycle The app component is a base class, with support for life-cycle events ( init, exec, done )
2. Envs Environment selection ( local, dev, qa, stg, prod, etc ) is available with integration with respective config files.
3. Overrides Support for overriding some settings on the command line with what is set up in the configuration file(s)
4. Context Container for services and items such as selected environment ( local, dev, etc ), config, logger, encryptor.
5. Help Support for app information, version, and command line args, is made available through config files and/or code

Back to top



Guide

>
Name Description More
Args Command line arguments ( -env=dev ) more
Envs Environment selection ( dev | qat | stg | pro ) more
Logs Logging and error handling ( console / file logger ) more
Conf Config settings ( env.conf, env.local.conf, env.qat.conf ) more
Context Application context ( for env, logs, configs, etc ) more
Cycle Life-Cycle events ( init, exec, done ) more
Help Help support for command line args ( help | version ) more
Info Startup info and diagnostics more
Security Setting up a secure application more

Args

Command line arguments are parsed and supplied to your app. You can specify what the arguments are supported by specifying the schema. This leverages the Args component.

  // Example of supplying arguments.
  myapp -env=dev -log.level=info -region=ny
    
  // setup the command line arguments.
  // NOTE:
  // 1. These values can can be setup in the env.conf file
  // 2. If supplied on command line, they override the values in .conf file
  // 3. If any of these are required and not supplied, then an error is display and program exists
  // 4. Help text can be easily built from this schema.
  val schema = ArgsSchema()
        .text("","env", "the environment to run in", false, "dev", "dev", "dev1|qa1|stg1|pro")
        .text("","region", "the region linked to app", false, "us", "us", "us|europe|india|*")
        .text("","log.level", "the log level for logging", false, "info", "info", "debug|info|warn|error")
    
Back to features Back to top


Envs

Default environments and configs per environment are setup for applications and associated together. Refer to example app and or a generated application for more info. This leverages the Envs and Config components

Env Name Mode Conf
Shared conf for all envs - - resources/env.conf
Development ( local ) loc Dev resources/env.local.conf
Development ( Shared ) dev Dev resources/env.dev.conf
Quality Assurance qat Qat resources/env.qat.conf
Staging stg Uat resources/env.uat.conf
Production pro Pro resources/env.pro.conf
Back to features Back to top


Logs

Logback logging is setup for the application in /resources/logback.xml This leverages the Logs component.

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    ...
    <logger name="app" level="info" additivity="false">
        <appender-ref ref="STDOUT" />
        <appender-ref ref="FILE" />
        <appender-ref ref="LOGGLY-ASYNC" />
    </logger>
    <root level="debug">
        <appender-ref ref="STDOUT" />
        <appender-ref ref="FILE" />
    </root>
    ...
</configuration>
Back to features Back to top


Conf

Configuration settings are supported via normal Java Properties files stored in the resources folder. Configuration settings existing based on the names of the environments setup ( see above ). This leverages the Config component.

env.conf

This is the common config file inherited by all other configs. You can specify the environment to load by setting env = name

# environment selection
# this can be overriden on the commandline via -env=qa
env = loc

env.qat.conf

You have config files per environment. You can override settings in the environment specific config.

# environment selection
# this can be overriden on the commandline via -env=qa
env = loc
Back to features Back to top


Help

The application supports typing -version, -about and -help after your apps executable/jar. This will display info about the app and usage of command line args. This leverages the Args component.

myapp -help

 ==============================================
 ABOUT
 area     :  Department 1
 name     :  Sample App
 desc     :  Sample console application to show the base application features
 url      :  http://sampleapp.slatekit.com
 contact  :  kishore@company1.co
 version  :  1.0.0
 tags     :  slate,shell,cli
 examples :  sampleapp -env=dev -log.level=debug -region='ny' -enc=false
 ==============================================

 ARGS
 -env     :  the environment to run in
             ! required  [String]  e.g. dev
 -log     :  the log level for logging
             ? optional  [String]  e.g. info
 -enc     :  whether encryption is on
             ? optional  [String]  e.g. false
 -region  :  the region linked to app
             ? optional  [String]  e.g. us
    
Back to features Back to top


Context

The is an application context that stores all relevant info about the application such as the command line args, config, logs, encryptor, info about the app and more. You have access to this with in your app. This can be either built up automatically by the application or you can supply it explicitly. This leverages the Context component. Here is an example of an explictly built context.

    // Build explicitly
    val ctx1 = AppEntContext(
            arg = Args.default(),
            env = Env("dev", EnvMode.Dev, "ny", "dev environment"),
            cfg = Config(),
            logs = LogsDefault,
            ent = Entities({ con -> Db(con) }),
            sys = Sys.build(),
            build = Build.empty,
            start = StartInfo.none,
            app = About(
                area = "department1",
                name = "sample-app-1",
                desc = "Sample application 1",
                company = "Company 1",
                region = "New York",
                url = "http://company1.com/dep1/sampleapp-1",
                contact = "dept1@company1.com",
                version = "1.0.1",
                tags = "sample app slatekit",
                examples = ""
            )
    )
       
Back to features Back to top


Cycle

The application support 3 life-cycle events, init, exec, and done. You can use these template methods to insert your pre execution, execution, and post execution logic.

    
    import slatekit.app.App
    import slatekit.results.Success
    import slatekit.results.Try
    import slatekit.common.CommonContext

    class SlateKit(ctx: CommonContext) : App<CommonContext>(ctx) {

        override suspend fun init(): Try<Boolean> {
            println("starting")
            return super.init()
        }

        override suspend fun exec(): Try<Any> {
            println("executing")
            return Success(true)
        }

        override suspend fun end(): Try<Boolean> {
            println("complete")
            return super.end()
        }
    }
    
Back to features Back to top


Info

The component can print diagnostic info during the start and end of your application life-cycle. This leverages the all the existing Args, Env, Config components list earlier.

 Info  : app executing now
 Info  : app completed
 Info  : app shutting down
 Info  : ===============================================================
 Info  : SUMMARY :
 Info  : ===============================================================
 Info  : area              = Samples
 Info  : name              = App1
 Info  : desc              = Sample to show the base application
 Info  : version           = 1.0.0
 Info  : tags              = sample
 Info  : contact           = kishore@abc.co
 Info  : url               =
 Info  : args              = -region=usa
 Info  : env               = dev
 Info  : config            = env.conf
 Info  : log               = local:dev
 Info  : started           = 2017-07-11T11:54:13.132-04:00[America/New_York]
 Info  : ended             = 2017-07-11T11:54:18.408-04:00[America/New_York]
 Info  : duration          = PT5.276S
 Info  : status            = ended
 Info  : host.name         = KRPC1
 Info  : host.ip           =
 Info  : host.origin       = mac
 Info  : host.version      = 10.0
 Info  : lang.name         = kotlin
 Info  : lang.version      = 1.8.0_91
 Info  : lang.vendor       = Oracle Corporation
 Info  : lang.java         = local
 Info  : App1              =  extra summary data1
 Info  : App1              =  extra summary data2
 Info  : ===============================================================

    
Back to features Back to top


Security

Sensitive configuration settings can be secured by encrypting the settings, or loading them from environment variables. Check the Config component for more info.

Back to features Back to top