easel.config

Class EaselConfigHelper<B extends ConfigBooleanEnum,I extends ConfigIntegerEnum,S extends ConfigStringEnum>

java.lang.Object

easel.config.EaselConfigHelper<B,I,S>

Type Parameters:

B - the type of the enum storing boolean options (defaults to ConfigBooleanEnum if not specified as an implementer of that interface)

I - the type of the enum storing integer options (defaults to ConfigIntegerEnum if not specified as an implementer of that interface)

S - the type of the enum storing string options (defaults to ConfigStringEnum if not specified as an implementer of that interface)

public class EaselConfigHelper<B extends ConfigBooleanEnum,I extends ConfigIntegerEnum,S extends ConfigStringEnum>
extends java.lang.Object

EXPERIMENTAL / UNSTABLE (API subject to change until easel 1.0.0)

An alternative system for managing config settings. It's mostly designed for more complicated systems where the amount of config options isn't known up front but may increase rapidly throughout development. Virtually all the effort for using this system is front-loaded, and adding new config options later is as simple as adding a row to an enum. With this system, there is no need to manually produce getter or setters for each config item, write (de)serialization code, etc. - it's all abstracted away through customizable enumerations. It has the added benefit of being partially type safe: allowing suggestions, code completion, and seeing fallback default values directly through your IDE. The backend of this config helper relies on hash maps to store and manage the data: getting a config option is O(1), while setting a config option to a different value is slightly more expensive as it will automatically save the entire group of options to disk when things change. The convenience of these benefits do not come free: there are some significant upfront development costs and limitations to this approach.

This system is NOT intended for simple or smaller use cases - if you only have a few config options, it is recommended that you do not follow this pattern as the boilerplate is substantial. The limitations of Java generics mixed with the verbosity required to make it work tend to make this method a bit too over-engineered for the vast majority of projects; however, larger projects with more complicated config reliance (e.g. the FilterTheSpire mod) can reap substantial benefits from using this setup.

To use this ConfigHelper, you need to first construct an enum for a particular type (that is: a Java type, such as a boolean or a String); all config options that share this Java type will be added inside this enum as you create them. E.g., all of your config options that determine a boolean value will be stored in a boolean specific enum. These enums are special, and should implement one of the Config(TYPE_HERE)Enum interfaces (i.e. an enum storing booleans should implement the ConfigBooleanEnum interface, an enum storing integers should implement the ConfigIntegerEnum interface, and an enum storing strings should implement the ConfigStringEnum interface. The string interface can be used to store much more complex serialization due to the ease of using a library like Gson to convert java classes into JSON formatted strings. For example, the MoveContainer can MoveContainer.toJsonString() and MoveContainer.loadFromJsonString(String) to/from a string that can then be managed by this config. There are examples showing how to implement the enum types included in the easel.config.samples package, e.g. SampleBooleanChoices, which you can find browsing the source code for Easel on Github.

The constants in these enums are laid out with the following pattern: OPTION_NAME(defaultValue), where defaultValue is what will get loaded the first time the mod is installed, or as a fallback if the mod cannot save/load config items for some reason (e.g. unable to save/load to/from disk due to the filesystem being READ-ONLY, out of space, etc.). By extending these interfaces, you are forced into making a getDefault() function for the ConfigHelper to hook into.

Once you have an enum for your options, you can proceed to construct the actual ConfigHelper using one of the included static factory methods. Here's an example where we use one of the sample implementations offered for boolean values (SampleBooleanChoices), which has two slots in its enum: a SampleBooleanChoices.BOOL_ONE that defaults to true, and SampleBooleanChoices.BOOL_TWO which defaults to false. We want to make sure our ConfigHelper can automatically setup all of these options from this SampleBooleanChoices class, so we construct it from the factory helper that takes from booleans only. Because the actual type of our configHelper variable is going to rely on generics (and essentially become unreadably messy), it's best to let your IDE figure out the type automatically for you. Using IntelliJ-IDEA, you can type the following line as is, and it will alert you that it "cannot resolve symbol" with some scary red text / squiggles on the configHelper variable itself (since it hasn't been declared yet). If you mouse over it and hit ALT+ENTER, you'll be able to select the option "create local variable" and have it figure out the type.

 
 configHelper = ConfigHelper.fromBooleansOnly(SampleBooleanChoices.class);
 
 

Letting it figure out the type allows it to fill out the entire line:

 
 ConfigHelper<SampleBooleanChoices, ConfigIntegerEnum, ConfigStringEnum> configHelper = ConfigHelper.fromBooleansOnly(SampleBooleanChoices.class);
 
 

Note that any of the pieces we did not set with a particular enum are given the placeholder types of the base interfaces, e.g. ConfigIntegerEnum. The argument(s) to these various static factory methods require you to take your particular enum and take its .class in order for the compiler to construct things nicely. Now, let's examine how to use this config helper to manage these config options.

To access a particular config option, we'll pass in an option from our enum into one of the getter functions:

 
 boolean booleanOne = configHelper.getBoolean(SampleBooleanChoices.BOOL_ONE); // returns true, since that was the default value for BOOL_ONE
 
 

Note that we get some type safety here - we're only allowed to pass in values from our enum which lists out all the possible config options we've defined, and the IDE / compiler can let us know if we screw something up. However, we're not fully protected here due to a limitation of this particular design: the other enum types were never initialized passed the placeholders (ConfigIntegerEnum etc.) and thus this particular ConfigHelper should ONLY be used for booleans (since that's all we chose in the factory method). Since IntelliJ-IDEA will suggest that "FOO" in the following example should be of type ConfigIntegerEnum, you may think you're safe because that placeholder doesn't have any options to choose from (and the compiler will prevent you from picking anything):

 
 int intOne = configHelper.getInt(FOO);
 
 

However, this isn't fully type safe, as you can pass in an option from something that DOES extend the ConfigIntegerEnum interface and the compiler will be totally fine with it, even though we never set up the ConfigHelper to refer to it as being a valid source! Thus, this will compile:

 
 int intOne = configHelper.getInt(SampleIntegerChoices.INT_ONE);
 
 

... but will result in a runtime crash due to an attempt to access a position in an array that hasn't been initialized. So to re-iterate: only use the ConfigHelper's getters and setters for the enum types you've actually setup when you constructed the ConfigHelper with the factory method, or you will crash. This limitation is why the ConfigHelper is only "partially" type-safe.

Setting a value is similar to getting one:

 
 configHelper.setBoolean(SampleBooleanChoices.BOOL_ONE, false);
 
 

As stated previously, as your project evolves and begins to require more config options, all you need to do is to go into your custom enums and add rows to them. Since the config helper relies on maps in the backend, you'll be able to easily add new options, stop referring to old options, and update your config cleanly as your project grows and your needs evolve. Should your config change dramatically enough between public releases, there are even helper functions like resetAllToDefaults(Class, Class, Class) which can automatically clean up previously saved data and remove everything but the currently used options.

For general design suggestions: you'd typically want to make your ConfigHelper a public static from inside your main class, and build it using the factory methods within a "postInitialize" subscription hook inside BaseMod. The factory methods will automatically attempt to load previously saved data from the disk (and then using the setters later will update and save the files as needed). With this pattern, other classes that need access to config options can just call MyMod.configHelper.getBoolean(...) etc. as they see fit. As a fair warning: this config helper is not thread safe so if you're trying to set config options from various threads you may run into race conditions.

The place this config gets saved to / loaded from is defined by the modName and configName options used by the factory methods: the modName should uniquely identify your mod (e.g. the id from your ModTheSpire.json), and the configName will define this particular set of config values. You may find it convenient to use multiple configName configs for a single mod (i.e. one modName for all, but multiple different ConfigHelpers each with a different configName), but usually a singular config is enough.

Method Summary

Modifier and Type	Method and Description
static <B extends ConfigBooleanEnum,I extends ConfigIntegerEnum> EaselConfigHelper<B,I,ConfigStringEnum>	fromBooleansIntegers(java.lang.String modName, java.lang.String configName, java.lang.Class<? extends B> booleanClz, java.lang.Class<? extends I> integerClz) Factory method to build from a boolean enum and an integer enum.
static <B extends ConfigBooleanEnum,I extends ConfigIntegerEnum,S extends ConfigStringEnum> EaselConfigHelper<B,I,S>	fromBooleansIntegersStrings(java.lang.String modName, java.lang.String configName, java.lang.Class<? extends B> booleanClz, java.lang.Class<? extends I> integerClz, java.lang.Class<? extends S> stringClz) Factory method to build from a boolean enum, an integer enum, and a string enum.
static <B extends ConfigBooleanEnum> EaselConfigHelper<B,ConfigIntegerEnum,ConfigStringEnum>	fromBooleansOnly(java.lang.String modName, java.lang.String configName, java.lang.Class<? extends B> booleanClz) Factory method to build from a boolean enum only.
static <B extends ConfigBooleanEnum,S extends ConfigStringEnum> EaselConfigHelper<B,ConfigIntegerEnum,S>	fromBooleansStrings(java.lang.String modName, java.lang.String configName, java.lang.Class<? extends B> booleanClz, java.lang.Class<? extends S> stringClz) Factory method to build from a boolean enum and a string enum.
static <I extends ConfigIntegerEnum> EaselConfigHelper<ConfigBooleanEnum,I,ConfigStringEnum>	fromIntegersOnly(java.lang.String modName, java.lang.String configName, java.lang.Class<? extends I> integerClz) Factory method to build from an integer enum only.
static <I extends ConfigIntegerEnum,S extends ConfigStringEnum> EaselConfigHelper<ConfigBooleanEnum,I,S>	fromIntegersStrings(java.lang.String modName, java.lang.String configName, java.lang.Class<? extends I> integerClz, java.lang.Class<? extends S> stringClz) Factory method to build from a boolean enum and a string enum.
static <S extends ConfigStringEnum> EaselConfigHelper<ConfigBooleanEnum,ConfigIntegerEnum,S>	fromStringsOnly(java.lang.String modName, java.lang.String configName, java.lang.Class<? extends S> stringClz) Factory method to build from a string enum only.
boolean	getBoolean(B choice)
int	getInt(I choice)
java.lang.String	getString(S choice)
boolean	load() Attempt to load in this config from disk.
boolean	resetAllToDefaults(java.lang.Class<B> booleanClz, java.lang.Class<I> integerClz, java.lang.Class<S> stringClz) Convenience: calls resetBooleansToDefaults(Class), resetIntegersToDefaults(Class), and resetStringsToDefaults(Class) all at once to completely rebuild the entire config structure.
boolean	resetBooleansToDefaults(java.lang.Class<B> booleanClz) Rebuilds the entire boolean storage structure and re-initializes them to their default values.
boolean	resetIntegersToDefaults(java.lang.Class<I> integerClz) Rebuilds the entire integer storage structure and re-initializes them to their default values.
boolean	resetStringsToDefaults(java.lang.Class<S> stringClz) Rebuilds the entire string storage structure and re-initializes them to their default values.
boolean	save() Attempt to save this config to disk.
boolean	setBoolean(B choice, boolean value) Set the given boolean option to this value.
boolean	setBooleanWithoutSaving(B choice, boolean value) A version of setBoolean(ConfigBooleanEnum, boolean) which does NOT automatically save the config.
boolean	setInt(I choice, int value) Set the given int option to this value.
boolean	setIntWithoutSaving(I choice, int value) A version of setInt(ConfigIntegerEnum, int) which does NOT automatically save the config.
boolean	setString(S choice, java.lang.String value) Set the given string option to this value.
boolean	setStringWithoutSaving(S choice, java.lang.String value) A version of setString(ConfigStringEnum, String) which does NOT automatically save the config.
java.lang.String	toString() Serializes the entire config (and all current values) as a JSON string.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

fromBooleansOnly

public static <B extends ConfigBooleanEnum> EaselConfigHelper<B,ConfigIntegerEnum,ConfigStringEnum> fromBooleansOnly(java.lang.String modName,
                                                                                                                     java.lang.String configName,
                                                                                                                     java.lang.Class<? extends B> booleanClz)

Factory method to build from a boolean enum only. Will automatically attempt to load existing values from disk during creation. See EaselConfigHelper for more details about this class.

Type Parameters:

B - the type of your enum

Parameters:

modName - the unique name of your mod (e.g. from your ModTheSpire.json's modid)

configName - the name of this particular config (you can have multiple config helpers per mod, each with a unique configName)

booleanClz - the class of your enum which extends ConfigBooleanEnum

Returns:

a usable config helper

fromIntegersOnly

public static <I extends ConfigIntegerEnum> EaselConfigHelper<ConfigBooleanEnum,I,ConfigStringEnum> fromIntegersOnly(java.lang.String modName,
                                                                                                                     java.lang.String configName,
                                                                                                                     java.lang.Class<? extends I> integerClz)

Factory method to build from an integer enum only. Will automatically attempt to load existing values from disk during creation. See EaselConfigHelper for more details about this class.

Type Parameters:

I - the type of your enum

Parameters:

modName - the unique name of your mod (e.g. from your ModTheSpire.json's modid)

configName - the name of this particular config (you can have multiple config helpers per mod, each with a unique configName)

integerClz - the class of your enum which extends ConfigIntegerEnum

Returns:

a usable config helper

fromStringsOnly

public static <S extends ConfigStringEnum> EaselConfigHelper<ConfigBooleanEnum,ConfigIntegerEnum,S> fromStringsOnly(java.lang.String modName,
                                                                                                                    java.lang.String configName,
                                                                                                                    java.lang.Class<? extends S> stringClz)

Factory method to build from a string enum only. Will automatically attempt to load existing values from disk during creation. See EaselConfigHelper for more details about this class.

Type Parameters:

S - the type of your enum

Parameters:

modName - the unique name of your mod (e.g. from your ModTheSpire.json's modid)

configName - the name of this particular config (you can have multiple config helpers per mod, each with a unique configName)

stringClz - the class of your enum which extends ConfigStringEnum

Returns:

a usable config helper

fromBooleansIntegers

public static <B extends ConfigBooleanEnum,I extends ConfigIntegerEnum> EaselConfigHelper<B,I,ConfigStringEnum> fromBooleansIntegers(java.lang.String modName,
                                                                                                                                     java.lang.String configName,
                                                                                                                                     java.lang.Class<? extends B> booleanClz,
                                                                                                                                     java.lang.Class<? extends I> integerClz)

Factory method to build from a boolean enum and an integer enum. Will automatically attempt to load existing values from disk during creation. See EaselConfigHelper for more details about this class.

Type Parameters:

B - the type of your boolean enum

I - the type of your integer enum

Parameters:

modName - the unique name of your mod (e.g. from your ModTheSpire.json's modid)

configName - the name of this particular config (you can have multiple config helpers per mod, each with a unique configName)

booleanClz - the class of your boolean enum which extends ConfigBooleanEnum

integerClz - the class of your integer enum which extends ConfigIntegerEnum

Returns:

a usable config helper

fromBooleansStrings

public static <B extends ConfigBooleanEnum,S extends ConfigStringEnum> EaselConfigHelper<B,ConfigIntegerEnum,S> fromBooleansStrings(java.lang.String modName,
                                                                                                                                    java.lang.String configName,
                                                                                                                                    java.lang.Class<? extends B> booleanClz,
                                                                                                                                    java.lang.Class<? extends S> stringClz)

Factory method to build from a boolean enum and a string enum. Will automatically attempt to load existing values from disk during creation. See EaselConfigHelper for more details about this class.

Type Parameters:

B - the type of your boolean enum

S - the type of your string enum

Parameters:

modName - the unique name of your mod (e.g. from your ModTheSpire.json's modid)

configName - the name of this particular config (you can have multiple config helpers per mod, each with a unique configName)

booleanClz - the class of your boolean enum which extends ConfigBooleanEnum

stringClz - the class of your string enum which extends ConfigStringEnum

Returns:

a usable config helper

fromIntegersStrings

public static <I extends ConfigIntegerEnum,S extends ConfigStringEnum> EaselConfigHelper<ConfigBooleanEnum,I,S> fromIntegersStrings(java.lang.String modName,
                                                                                                                                    java.lang.String configName,
                                                                                                                                    java.lang.Class<? extends I> integerClz,
                                                                                                                                    java.lang.Class<? extends S> stringClz)

Factory method to build from a boolean enum and a string enum. Will automatically attempt to load existing values from disk during creation. See EaselConfigHelper for more details about this class.

Type Parameters:

I - the type of your integer enum

S - the type of your string enum

Parameters:

modName - the unique name of your mod (e.g. from your ModTheSpire.json's modid)

configName - the name of this particular config (you can have multiple config helpers per mod, each with a unique configName)

integerClz - the class of your integer enum which extends ConfigIntegerEnum

stringClz - the class of your string enum which extends ConfigStringEnum

Returns:

a usable config helper

fromBooleansIntegersStrings

public static <B extends ConfigBooleanEnum,I extends ConfigIntegerEnum,S extends ConfigStringEnum> EaselConfigHelper<B,I,S> fromBooleansIntegersStrings(java.lang.String modName,
                                                                                                                                                        java.lang.String configName,
                                                                                                                                                        java.lang.Class<? extends B> booleanClz,
                                                                                                                                                        java.lang.Class<? extends I> integerClz,
                                                                                                                                                        java.lang.Class<? extends S> stringClz)

Factory method to build from a boolean enum, an integer enum, and a string enum. Will automatically attempt to load existing values from disk during creation. See EaselConfigHelper for more details about this class.

Type Parameters:

B - the type of your boolean enum

I - the type of your integer enum

S - the type of your string enum

Parameters:

modName - the unique name of your mod (e.g. from your ModTheSpire.json's modid)

configName - the name of this particular config (you can have multiple config helpers per mod, each with a unique configName)

booleanClz - the class of your boolean enum which extends ConfigBooleanEnum

integerClz - the class of your integer enum which extends ConfigIntegerEnum

stringClz - the class of your string enum which extends ConfigStringEnum

Returns:

a usable config helper

getBoolean

public boolean getBoolean(B choice)

Parameters:

choice - a choice in the boolean enum

Returns:

the current value of this particular choice or the default value if it doesn't exist yet

setBoolean

public boolean setBoolean(B choice,
                          boolean value)

Set the given boolean option to this value. Automatically attempts to save if the value is different than the current one, and then returns true if the save was successful.

Parameters:

choice - a choice in the boolean enum

value - the new value of this particular choice

Returns:

true if the value is new and the config was successfully saved; false if the value existed already or if something went wrong when saving (there will be a stack trace if IO failed)

getInt

public int getInt(I choice)

Parameters:

choice - a choice in the integer enum

Returns:

the current value of this particular choice or the default value if it doesn't exist yet

setInt

public boolean setInt(I choice,
                      int value)

Set the given int option to this value. Automatically attempts to save if the value is different than the current one, and then returns true if the save was successful.

Parameters:

choice - a choice in the integer enum

value - the new value of this particular choice

Returns:

true if the value is new and the config was successfully saved; false if the value existed already or if something went wrong when saving (there will be a stack trace if IO failed)

getString

public java.lang.String getString(S choice)

Parameters:

choice - a choice in the string enum

Returns:

the current value of this particular choice or the default value if it doesn't exist yet

setString

public boolean setString(S choice,
                         java.lang.String value)

Set the given string option to this value. Automatically attempts to save if the value is different than the current one, and then returns true if the save was successful.

Parameters:

choice - a choice in the string enum

value - the new value of this particular choice

Returns:

true if the value is new and the config was successfully saved; false if the value existed already or if something went wrong when saving (there will be a stack trace if IO failed)

setBooleanWithoutSaving

public boolean setBooleanWithoutSaving(B choice,
                                       boolean value)

A version of setBoolean(ConfigBooleanEnum, boolean) which does NOT automatically save the config. You can use this variant to set multiple options in bulk before saving, instead of saving after each individual change. This pattern can be used to improve performance in some cases. Remember to call save() later in order for these set values to persist.

Parameters:

choice - a choice in the boolean enum

value - the new value of this particular choice

Returns:

true if the new value is different than the one previously stored by the map

setIntWithoutSaving

public boolean setIntWithoutSaving(I choice,
                                   int value)

A version of setInt(ConfigIntegerEnum, int) which does NOT automatically save the config. You can use this variant to set multiple options in bulk before saving, instead of saving after each individual change. This pattern can be used to improve performance in some cases. Remember to call save() later in order for these set values to persist.

Parameters:

choice - a choice in the integer enum

value - the new value of this particular choice

Returns:

true if the new value is different than the one previously stored by the map

setStringWithoutSaving

public boolean setStringWithoutSaving(S choice,
                                      java.lang.String value)

A version of setString(ConfigStringEnum, String) which does NOT automatically save the config. You can use this variant to set multiple options in bulk before saving, instead of saving after each individual change. This pattern can be used to improve performance in some cases. Remember to call save() later in order for these set values to persist.

Parameters:

choice - a choice in the string enum

value - the new value of this particular choice

Returns:

true if the new value is different than the one previously stored by the map

toString

public java.lang.String toString()

Serializes the entire config (and all current values) as a JSON string.

Overrides:

toString in class java.lang.Object

Returns:

json formatted string auto-generated by Gson

save

public boolean save()

Attempt to save this config to disk. Not needed if you use the regular setters (as the saving will occur automatically). Only necessary to call this after using something like setBooleanWithoutSaving(ConfigBooleanEnum, boolean), which are intended to let you set the values in bulk and save only at a designated time.

Returns:

true if the save is successful; if it fails and returns false, there should be an IOException stack trace

load

public boolean load()

Attempt to load in this config from disk. Called automatically by the factory methods and almost never needed to be called manually. Uses the modName and configName set by the factory methods to identify which file to load.

Returns:

true if was able to find and successfully load the file

resetBooleansToDefaults

public boolean resetBooleansToDefaults(java.lang.Class<B> booleanClz)

Rebuilds the entire boolean storage structure and re-initializes them to their default values. Attempts to save the new settings afterwards.

Parameters:

booleanClz - the enum class for the boolean options

Returns:

true if the save is completed successfully

resetIntegersToDefaults

public boolean resetIntegersToDefaults(java.lang.Class<I> integerClz)

Rebuilds the entire integer storage structure and re-initializes them to their default values. Attempts to save the new settings afterwards.

Parameters:

integerClz - the enum class for the integer options

Returns:

true if the save is completed successfully

resetStringsToDefaults

public boolean resetStringsToDefaults(java.lang.Class<S> stringClz)

Rebuilds the entire string storage structure and re-initializes them to their default values. Attempts to save the new settings afterwards.

Parameters:

stringClz - the enum class for the string options

Returns:

true if the save is completed successfully

resetAllToDefaults

public boolean resetAllToDefaults(java.lang.Class<B> booleanClz,
                                  java.lang.Class<I> integerClz,
                                  java.lang.Class<S> stringClz)

Convenience: calls resetBooleansToDefaults(Class), resetIntegersToDefaults(Class), and resetStringsToDefaults(Class) all at once to completely rebuild the entire config structure.

Parameters:

booleanClz - the enum class for the boolean options

integerClz - the enum class for the integer options

stringClz - the enum class for the string options

Returns:

true if the save is completed successfully