Working with KelpConfigurations

Why use KelpConfigurations?

KelpConfigurations are a good way to simplify your attribute-based configurations for message configs, etc. It is not meant to use it for object notation like JSON is. You can easily save and retrieve key-value-based data.

How to create a KelpConfiguration?

Each configuration file has its own class. Make sure this class is a singleton (has @Singleton annotation by Guice) in order to keep the attributes correctly over the server runtime. Then add a second annotation:

@Singleton
@Configuration(name = "messages",
        path = "kelp_plugins//YourPlugin",
        type = PropertiesConfigurationType.class
)
public final class MyExampleConfiguration {

}

• name: The name of your configuration file (without file extension)
• path: The path, where your configuration file should be stored. It starts at the server folder.
• type: The configuration type. This defines the file extension and format of the file. In this case, the configuration will be stored in a .properties file. This is very powerful as it allows you to change your configuration type on the fly without adjusting anything else if you need to do so.

Furthermore, your class has to inherit from KelpConfiguration and override its method:

@Singleton
@Configuration(name = "messages",
  path = "kelp_plugins//YourPlugin",
  type = PropertiesConfigurationType.class
)
public class MyExampleConfiguration extends KelpConfiguration {

  @Override
  public void defineDefaults() {

  }

}

Defining default values

Defining the default values for your attributes is obviously done with the defineDefaults() method. Inside it you can use #add(key, value) to add a new attribute:

@Override
public void defineDefaults() {
  add("test.message", "§aThis is a test message");
  add("test.maxPlayers", 20);
  add("test.banOnDeath", false);
}

You can use any Java data type you want. It will be automatically converted by Kelp if needed.

Retrieving values

To retrieve a value from your config file, you have to get an instance of your configuration class (inject it via Guice). It contains the following methods to retrieve values:

• getIntValue(String key): Gets an integer with the given key.
• getStringValue(String key): Gets a string with the given key.
• getBooleanValue(String key): Gets a boolean with the given key.
• getFloatValue(String key): Gets a float with the given key.
• getDoubleValue(String key): Gets a double with the given key.
• getLongValue(String key): Gets a long with the given key.

An example might look like this:

public class MyExampleConfigUsage {

  private MyExampleConfiguration configuration;

  @Inject
  public MyExampleConfigUsage(MyExampleConfiguration configuration) {
    this.configuration = configuration;
  }

  public void doSomething() {
    System.out.println(configuration.getStringValue("test.message")); // <----
  }

}

How to use replacements

Replacements are a feature of string values. They become essential if you want to use prefixes in your messages and want to keep them maintainable.

They work pretty much like the Java MessageFormat as they use it in the background, so the use of replacements in Kelp will be familiar to you:

@Override
public void defineDefaults() {
  add("test.prefix", "[KELP]");
  add("test.welcomeMessage", "{0} Welcome on the server!", getStringValue("test.prefix"));
}

This code snippet replaces {0} with the previously defined prefix ('[KELP]'). If you want to add another replacement, simply use {1}, {2}, {3}, etc. and append your replacement values in a chronological order.

Loading your config files

You won't be able to retrieve values if you have not loaded your config before. This is done by calling the #loadAll(packages) method in the ConfigurationRepository. You have to pass the packages where your config classes are located as a parameter.

injector.getInstance(ConfigurationRepository.class).loadAll(this.getClass().getPackage().getName());