Live-Code Quickstart

Get started by trying live code examples in Replit

Let's get started! Below is a live demo REPL that is ready to run five simple demos. Go ahead and click the Green run button.

Overview

If you haven't already, go ahead and click the green run button at the top of the REPL window above.

Running this REPL compiles a small AndHow example, then runs it five times with different configurations. Take a look at the Main class: It contains two AndHow Properties, NAME & REPEAT_COUNT. The values of these two Properties are used to print to System.out in the main method.

There is also an andhow.properties file - click the file icon on the left to see the list of files. The file has a value for both Properties. (You can click the file icon again to make the list go away).

Continue on to the Run 1 tab. . .

This REPL is hosted by Repl.it. You can work on the Console or the Shell without logging in, but you need to login with a free accont to work on a fork to modify code or files.

If you try to run commands on the console and get an error like this:

Error: Could not find or load main class Main Caused by: java.lang.ClassNotFoundException: Main

Your VM has timed out - Just click the green run button again to rebuild everything.

Run 1

You probably have to scroll back up to the top of the black Console window, above, to see the output of Run 1.

Run 1 prints: Hello, Dawn! Hello, Dawn!

AndHow found and loaded the values for the two Properties from the andhow.properties file as soon as the code tried to access a Property value (Main line 13). By default, AndHow will always attempt to read property values from that file.

The command in yellow:

java -cp .:target/dependency/*:target/classes Main

...is the command that ran this example. You can copy and paste it in the console and run it again. Clicking the green run button will compile the code and run all four examples again - you don't need to click the run button again unless you want to see the whole thing run again.

Continue on to the Run 2 tab, and so on. . .

Run 2

Run 2 prints: Hello, Darcey! Hello, Darcey!

In this example, an environment variable named Main.NAME is set to Darcey and the java command is run with that variable set.

AndHow scans the environment variable names for any that match a Property and assigns Darcey to the NAME Property. For AndHow, env. vars. take precidence over values from property files, so Darcey is used instead of Dawn. The REPEAT_COUNT value of 2 is still taken from the properties file.

AndHow has a well defined priority order of configuration sources that works for most situations and the ability to change the order if needed.

Run 3

Run 3 prints: Hello, Dave! Hello, Dave!

This time NAME is set as a java system property via the -D argument. AndHow can read configuration from many different sources.

Run 4

Run 4 prints: Hello, Demi! Hello, Demi!

The java command arguments after the class name are passed to the main(String[] args) method. The main method includes this bit of code:

AndHow.findConfig().setCmdLineArgs(args);

AndHow can load values from most configuration sources automatically, however, it has no way to intercept the command line arguments passed to the main method - the application has to help by passing them to AndHow. Read more about how findConfig() works.

Run 5

Run 5 uses a system property to set NAME to an invalid value

NAME in the Main class is built with startsWith("D") - It must start with D as all the examples have done. What happens if that rules is broken?

This example was saved for you to run. Copy and paste the yellow comand in the console window:

java -cp .:target/dependency/*:target/classes -DMain.NAME=Bob Main

...Did you run it?

AndHow validates all configuration values at startup and throws a RuntimeExcpetion to fail fast and prevent an application from running with invalid configuration. The validation errors and messages AndHow gives are very specific:

Property Main.NAME loaded from java.lang.System.getProperties(): The value 'Bob' must start with 'D'

It tells us where the value was loaded from and exactly what validation rule the potential configuration value broke. It also includes a message like this:

A set of sample configuration files will be written to '/tmp/andhow-samples/'

When a startup error happens, AndHow helpfully creates configuration templates. These templates are rich and detailed files that serve as documentation for application configuration and a starting point for creating a properties configuration file. You can list and view the contents in the console:

ls /tmp/andhow-samples/     (your path may be different)
  - JNDI.xml
  - PropertyFile_KeyValuePair.properties
more /tmp/andhow-samples/PropertyFile_KeyValuePair.properties

Here is a portion from the PropertyFile_KeyValuePair.properties file - a template file you can use to create your own andhow.properties file:

# 
# NAME (String) NON-NULL
# The property value must start with 'D'
Main.NAME = 

# 
# REPEAT_COUNT (Integer) NON-NULL
# The property value must be less than 5
Main.REPEAT_COUNT = 

Where to go next

The User Guide has a suggested learning path - Happy trails!

&?!