Tutorial

Creating a configuration

Let's say you want to create the following web chat configuration:

# This is the default WebChat configuration
# Author: John Doe

ipAddress: 127.0.0.1
port: 12345
# Users mapped to users
users:
  User1:
    email: user1@example.com
    credentials:
      username: User1
      password: '12345'
  User2:
    email: user2@example.com
    credentials:
      username: User2
      password: '54321'
  User3:
    email: user3@example.com
    credentials:
      username: User3
      password: '51423'
channels:
- id: 1
  name: Channel1
  owner: User1
  members:
  - User2
  - User3
- id: 2
  name: Channel2
  owner: User2
  members:
  - User1

1. Create a configuration

Create a class which extends de.exlll.configlib.Configuration.

import de.exlll.configlib.Configuration;

import java.nio.file.Path;

public final class WebchatConfig extends Configuration {
    public WebchatConfig(Path configPath) {
        super(configPath);
    }
}

2. Create custom classes (optional)

Create some classes to hold the necessary information. Be aware that custom classes must have a no-arguments constructor.

import de.exlll.configlib.Configuration;

import java.nio.file.Path;
import java.util.List;

public final class WebchatConfig extends Configuration {
    public WebchatConfig(Path configPath) {
        super(configPath);
    }

    private static final class User {
        private String email;
        private Credentials credentials;
    }

    private static final class Credentials {
        private String username;
        private String password;
    }

    private static final class Channel {
        private int channelId;
        private String channelName;
        private String owner;         // username of the owner
        private List<String> members; // other user names
    }
}

3. Add attributes

You can add attributes to configuration class whose type is one of the following:

• a simple type, which are all primitive types (e.g. boolean, int), their wrapper types (e.g. Boolean, Integer) and strings
• Lists, Sets and Maps of simple types (e.g List<Double>) or other lists, sets and maps (e.g. List<List<Map<String, Integer>>>)
• custom types which have a no-argument constructor,
• ConfigLists, ConfigSets and ConfigMaps of custom types

If you want to use lists, sets or maps containing objects of custom types, you have to use ConfigList, ConfigSet or ConfigMap, respectively. If you don't use these special classes for storing custom objects, the stored objects won't be properly (de-)serialized.

NOTE: all attribute values must be non-null. If any value is null, serialization will fail with a NullPointerException.

import de.exlll.configlib.ConfigList;
import de.exlll.configlib.ConfigMap;
import de.exlll.configlib.Configuration;

import java.nio.file.Path;
import java.util.List;
import java.util.Map;

public final class WebchatConfig extends Configuration {
    private String ipAddress = "127.0.0.1";
    private int port = 12345;
    private Map<String, User> users = new ConfigMap<>(String.class, User.class);
    private List<Channel> channels = new ConfigList<>(Channel.class);

    public WebchatConfig(Path configPath) {
        super(configPath);
    }

   /* other classes and methods */
}

4. Add comments

Comments can only be added to the configuration class or its attributes. Comments you add to other custom classes or their attributes will be ignored.

import de.exlll.configlib.Comment;
import de.exlll.configlib.ConfigList;
import de.exlll.configlib.ConfigMap;
import de.exlll.configlib.Configuration;

import java.nio.file.Path;
import java.util.List;
import java.util.Map;

@Comment({
        "This is the default WebChat configuration",
        "Author: John Doe"
})
public final class WebchatConfig extends Configuration {
    private String ipAddress = "127.0.0.1";
    private int port = 12345;
    @Comment("Users mapped to users")
    private Map<String, User> users = new ConfigMap<>(String.class, User.class);
    private List<Channel> channels = new ConfigList<>(Channel.class);

    public WebchatConfig(Path configPath) {
        super(configPath);
    }

   /* other classes and methods */
}

5. Add default values.

Add some default values for list, sets and maps.

/* imports */
public final class WebchatConfig extends Configuration {
    /* attributes */

    public WebchatConfig(Path configPath) {
        super(configPath);

        Channel channel1 = createNewChannel(1, "Channel1", "User1",
                Arrays.asList("User2", "User3"));
        Channel channel2 = createNewChannel(2, "Channel2", "User2",
                Arrays.asList("User1"));
        channels.add(channel1);
        channels.add(channel2);

        User user1 = createNewUser("user1@example.com", "User1", "12345");
        User user2 = createNewUser("user2@example.com", "User2", "54321");
        User user3 = createNewUser("user3@example.com", "User3", "51423");

        users.put(user1.credentials.username, user1);
        users.put(user2.credentials.username, user2);
        users.put(user3.credentials.username, user3);
    }

    private Channel createNewChannel(int id, String name, String owner,
                                     List<String> members) {
        Channel channel = new Channel();
        channel.id = id;
        channel.name = name;
        channel.owner = owner;
        channel.members = members;
        return channel;
    }

    private User createNewUser(String email, String username, String password) {
        Credentials credentials = new Credentials();
        credentials.username = username;
        credentials.password = password;
        User user = new User();
        user.email = email;
        user.credentials = credentials;
        return user;
    }
    
   /* other classes and methods */
}