Tutorial

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. step

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. step

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

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. step

Add attributes. If you want to use lists, sets or maps containing objects of custom classes, you have to use ConfigList, ConfigSet, ConfigMap, respectively. If you use other map types or collections (e.g. ArrayList), your objects won't be properly (de-)serialized. However, you can still use other map types and collections for simple types like String or Integer.

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. step

Add comments.

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. step

Add default values.

/* 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 */
}