Overview #

In factory tutorial Part 2 we used an enum to tell the factory method getDataStore() of the DataStoreFactory which instance of the DataStore to create.

...

public enum DataStoreType {
    DATABASE,
    TEXTFILE,
    MOCK
}

public class DataStoreFactory {

    ...

    public static DataStore getDataStore(DataStoreType type, String connectionString) {
        switch (type) {
            case DATABASE:
                return new DatabaseDataStoreImpl(connectionString);
            case TEXTFILE:
                return new TextFileDataStoreImpl(connectionString);
            case MOCK:
                return new MockDataStoreImpl();
            default:
                throw new IllegalArgumentException("Unknown data store type");
        }
    }

}

In real-world applications, it is common to load configuration settings via a configuration service rather than passing them as parameters. This service retrieves configuration items from property files or key value stores, allowing the application to adapt to different environments such as development, testing, and production. For instance, in a development environment, news might be loaded using TextFileDataStoreImpl for easy modification via text files. In a testing environment, MockDataStoreImpl could be used to facilitate automated testing with predictable data. In a production environment, DatabaseDataStoreImpl would be employed to fetch real news from a live database.

One of the key advantages of using a configuration service is that it removes the necessity to alter the application code when transitioning between different environments. The application seamlessly adjusts to the unique requirements of each environment based on the provided configurations.

By leveraging this approach, maintainability is improved, and the likelihood of errors is minimized.

Excursus: Java Virtual Machine (JVM), .class Files, classpath, ClassLoader and Build Tools #

To run Java code, Java source code needs to be compiled to Java byte code. For example, let us assume we have a simple App.java source file containing an App class that prints Hello, World! to the console

public class App {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}

To run this application, we first need to compile it to byte code. Byte code are the low level instructions that can be interpreted by the Java virtual machine (JVM). Byte code is similar to native object code that is produced, e.g., by a compiler for a C program. However, byte code is executed by a “virtual processor”, i.e., the JVM, whereas native object code is directly executed by the microprocessor of the machine. This mechanisms allows to run Java programs on any machine a JVM is available for, irrespective of the microprocessor architecture such as x86, x64, ARM, MIPS, RISC V and the like. From this fact the slogan “Write once, run anywhere” originates. To compile a Java source file to byte code we run

$ javac App.java

The javac compiler produces a file named App.class which then can be executed by the JVM

$ java App
Hello, World!
$

Behind the scenes, the JVM searches for the compiled class App.class on the classpath. It then loads App.class into the JVM with the ClassLoader. In simple terms, the ClassLoader reads App.class from the filesystem into the memory of the JVM. It then interprets the loaded byte code from App.class to run the program.

The classpath is simply a list of folders on the filesystem where the JVM should search for .class files required by the application. The JVM also searches for .class files in Java ARchive (JAR) .jar files that are listed on the classpath. JAR files are simple archives containing .class files. In fact, the file format is a .zip file of a folder structure containing .class files - renamed to .jar. In addition to the .class files, the archive contains some metadata in a folder named META-INF. You can extract any .jar file with any archiver that can read .zip files. With .jar files, software libraries such as TestNG, can be easily distributed and used by listing it on the classpath.

Now, let us assume we work on a helloworld project. Our source files reside in a src folder, our class files reside in a bin folder and our library files reside in a lib folder. Let us further assume we use the TestNG library for automated testing. Our project structure would look similar to

helloworld
└── src
    └── App.java
    └── AppTest.java
└── bin
    └── App.class
    └── AppTest.class
└── lib
    └── testng-7.5.1.jar
    └── ...

To build our source files to .class files in above structure, we would need to issue following command in the helloworld folder

javac src/App.java src/AppTest.java -classpath "lib/testng-7.5.1.jar" -d bin

To run our tests in AppTest.java we would need to issue

$ java -classpath "lib/testng-7.5.1.jar:bin" org.testng.TestNG AppTest

The colon : separates different classpath items such as lib/testng-7.5.1.jar and the bin folder in a unix-like environment. In a Windows environment, we would need to separate the classpath items with a semicolon ;. With these -classpath arguments, the JVM would search for org/testng/TestNG.class and related files in lib/testng-7.5.1.jar and for our AppTest.class in the bin folder.

Further information about classpath and .jar is available from the articles Back to the basics of Java Part 1 and Part 2

The steps above are quite complex for running a simple program and some basic automated tests. Thankfully, build tools like Gradle or Maven come to rescue. They automatically download and manage dependencies, such as testng-7.5.1.jar including its transitive dependencies, i.e. libraries testng-7.5.1.jar depends itself on, build all source files, and run tests and the application. In our examples, we commonly use Gradle. When creating a new Java project in Visual Studio Code and selecting Gradle as the build tool, Visual Studio Code automatically scaffolds a Gradle project structure, creating all the required folders and files needed for our project.

By convention, Gradle expects all Java source files for the application to be located in src/main/java. Additionally, resource files such as configuration files, text files, and images should be placed in src/main/resources. For automated testing, Java source files should be in src/test/java, and resource files should be in src/test/resources. Gradle uses these files along with a build.gradle configuration file to build, test and run the application.

A typical Gradle project has following structure

helloworld
└── build
│   └── ...                           -> the build files created by Gradle
│   └── ...
│
└── src
│   └── main
│   │   └── java 
│   │   │   └── academy
│   │   │   │   └── majikmate
│   │   │   │       └── newsbroker
│   │   │   │           └── NewsAgency.java
│   │   │   │           └── ...      
│   │   │   │
│   │   │   └── App.java
│   │   │
│   │   └── resources 
│   │       └── app.properties        -> app.properties for application  
│   │       └── ...                   -> other resource files for application
│   │   
│   └── test
│       └── java 
│       │   └── AppTest.java
│       │
│       └── resources 
│           └── app.properties        -> app.properties for tests
│           └── ...                   -> other resource files for tests
│
└── build.gradle                      -> the gradle configuration file      

With a project structure as above, we simply issue

$ gradle build

to build and test the application. Gradle automatically assembles the classpath, hands it to javac and generates all the .class files. It then assembles the classpath to test the application, hands it to java and executes org.testng.TestNG to run all the tests. We issue

$ gradle test 

to only build and run the tests for our application and

$ gradle run 

to run the application. We issue

$ gradle clean 

to cleanup the project folder and remove all generated build artifacts.

During the build process, Gradle places all compiled files from src/main/java respectively src/test/java and files from src/main/resources respectively src/test/resources onto the classpath. This allows us to load configuration files, such as app.properties, directly from the classpath, without needing to know their exact filesystem locations. Gradle manages the project files based on the context: it includes files from src/main/java and src/main/resources when running the application and files from src/test/java and src/test/resources when running tests. This ensures that the application always loads app.properties from the appropriate context, with Gradle handling the file switching automatically based on whether the application is in run mode or test mode. Moreover, this structure helps to separate application files and test files into different locations, creating a clean and clear project structure.

Simple Configuration Service #

Java brings a Properties class in package java.util for managing simple key / value pairs of configuration data. The full javadoc is available at java.util.Properties. For our example, such a file could look like follows.

# specifies the environment the application is running
# valid values for key 'environment' are:
#   - 'development' for the development environment
#   - 'test' for the testing environment
#   - 'production' for the production environment
environment = development

# specifies the database connection string for the specified environment
# valid values for key 'database' are:
#   - any file path to a text file
#   - 'mock' for the testing environment
#   - any jdbc connection string, e.g., 'jdbc:sqlite:db.sqlite', for the production environment
database = news.txt

We name this file app.properties and save it into the src/main/resources folder so that it can be loaded from the java classpath.

To manage configurations, we create a new package academy.majikmate.config and create our configuration service

public class Config {

    private final Properties properties;

    ...

    public Config() {
        this.properties = new Properties();
    }

    ...

}

It is good practice to define strings such as the config file name, keys and values used in property files as string constants within the Config class

public class Config {

    ...

    private static final String CONFIG = "app.properties";

    private static final String ENVIRONMENT = "environment";
    private static final String DATABASE = "database";

    ...

}

Please notice that we declare the keys of the properties as private because they are only used inside the Config class, as shown below. Please also notice the final modifier that makes the defined strings as constants that cannot be overwritten.

We now can implement access methods to our configuration values

public class Config {

    ...

    public String getEnvironment() {
        return properties.getProperty(ENVIRONMENT);
    }

    public String getDatabase() {
        return properties.getProperty(DATABASE);
    }

    ...

}

Finally, we need to load the properties file from the classpath. We do this in our constructor so that the properties are available from the access methods

public class Config {

    ...

    public Config() {
        
        ...
        
        properties.load(getClass().getClassLoader().getResourceAsStream(CONFIG));
    }

    ...

}

getClass() is a method available from the java.lang.Object class which every class automatically inherits in Java. You can review the full javadoc about java.lang.Object here. It gives access to metadata about the class of the current object such as the class name. You can review the full javadoc here. Beyond metadata about the class, it gives access to the ClassLoader the class was loaded with into the JVM. We can utilize this ClassLoader to also load our app.properties configuration file from the classpath. We utilize the getResourceAsStream method read the file from the filesystem.

Because reading a file from the filesystem can fail, getResourceAsStream can throw an Exception to indicate something went wrong with the filesystem operation, e.g., when the file cannot be found. Hence, we need to handle this Exception in a try ... catch block

public class Config {

    ...

    public Config() {

        ...

        try {
            properties.load(getClass().getClassLoader().getResourceAsStream(CONFIG));
        } catch (Exception e) {
            throw new IllegalStateException("could not load app.properties", e);
        }

        ...

    }

    ...

}

Whenever we experience an issue with loading our app.properties file, we assume this as a fatal error and indicate to terminate the application to the users of our config service. We do this by throwing a new IllegalStateException indicating that we could not load the app.properties file. Please take it as is, more on error and exception handling in another tutorial.

We further can enhance the robustness of our application by checking the values of our properties. For example, we clearly know that our environment property can only take on the values development, test, and production. We can check for these values in our access methods.

We first declare the constants of valid values in our Config class

public class Config {

    ...

    public static final String ENVIRONMENT_DEVELOPMENT = "development";
    public static final String ENVIRONMENT_TEST = "test";
    public static final String ENVIRONMENT_PRODUCTION = "production";

    ...

Please notice that we declare the values of the properties as public because we later will need these constants also in our factory class outside the Config class. Again, notice the final modifier to make them immutable.

We now can check the loaded values from the properties file

public class Config {

    ...

    public String getEnvironment() {
            var value = properties.getProperty(ENVIRONMENT);
            switch (value) {
                case null:
                    throw new IllegalStateException("key 'environment' does not exist in app.properties");           
                case 
                        ENVIRONMENT_DEVELOPMENT, 
                        ENVIRONMENT_TEST, 
                        ENVIRONMENT_PRODUCTION: 
                    return value;
                default:
                    throw new IllegalStateException("invalid value for property environment: '" + value + "'");
            }
        }

    ...

}

The switch statement is a shortcut for multiple if else statements. For each case it checks if the case expressions equals the value given to the switch statement. A case can match multiple values, such as with ENVIRONMENT_DEVELOPMENT, ENVIRONMENT_TEST, and ENVIRONMENT_PRODUCTION. If value does not match any of the cases, the default case is executed. Read more about the switch statement here

Please notice that we also check for the null value. Properties inherit from java.util.Hashtable. If a key does not exist, getProperty returns the null value. Hence, by explicitly checking for the null value, we can check wether or not the property respectively the key exists in our app.properties file.

Similarly, getDatabase() would check if the database key is available in app.properties and wether or not a value is assigned to the key

public class Config {

    ...

    public String getDatabase() {
        var value = properties.getProperty(DATABASE);
        if (value == null) {
            throw new IllegalStateException("key 'database' does not exist in app.properties");
        } else {
            return value;
        }
    }

    ...

}

Usage of the Configuration Service #

With the introduction configuration service, we now can modify our factory to use the configuration from our app.properties configuration file.

public class DataStoreFactory {

    ...

    public static DataStore getDataStore() {

        final Config config = new Config()

        switch (config.getEnvironment()) {
            case Config.ENVIRONMENT_DEVELOPMENT:
                return new TextFileDataStoreImpl(config.getDatabase());
            case Config.ENVIRONMENT_TEST:
                return new MockDataStoreImpl();
            case Config.ENVIRONMENT_PRODUCTION:
                return new DatabaseDataStoreImpl(config.getDatabase());
            default:
                throw new IllegalStateException("unknown environment: '" + config.getEnvironment() + "'");
        }
    }

    ...

}

We use the public constants we defined on our Config service to check the cases in our switch statement. This allows our getDataStore() factory method to decide which DataStore implementation to instantiate. The default case again throws an IllegalStateException to indicate the users of the DataStoreFactory to terminate in case an unknown environment is loaded. This further helps to improve the robustness of our application. In case the configuration service is extended to accept environments that are currently unknown to the DataStoreFactory, it deliberately terminates the program because the factory does not know how to instantiate a DataStore. As a general rule, switch statement always should have a default case so that the switch statement never can “fall through” without being handled.

Model and Implementation #

With the addition of the configuration service the class diagram for the news broker application would look as follows

In main of the application, a DataStore would be instantiated using the parameter-less factory method getDataStore() from DataStoreFactory.

public static void main(String[] args) {

    ...

    var datastore = DataStoreFactory.getDataStore()
    var apa = new NewsAgency(datastore, "reuters")

    ...

}

Summary #

In this tutorial we learned about the the implementation of a configuration service in Java using the Properties class to manage environment-specific settings. It explains how to load configuration files from the classpath and use them to determine the appropriate DataStore implementation in a factory pattern. The tutorial also provides an excursus on the Java Virtual Machine (JVM), classpath, and build tools like Gradle to manage dependencies and automate the build process. By following these practices, developers can create maintainable and adaptable applications that seamlessly switch between different environments.