DataExtension API Builders

DataExtension API - Builders

DataExtension Builder APIs require DATA_EXTENSION_BUILDER_API capability.

---

🧰 @DataBuilderProvider annotation

Speciality: Allows you to add data dynamically.

Example use case: Display user configured placeholders

Usage:

@DataBuilderProvider
public ExtensionDataBuilder lotsOfData(UUID playerUUID) {
    ExtensionDataBuilder builder = newExtensionDataBuilder();
    ...
    return builder;
}

Adding values

You can add all the same kinds of values as with the annotation API. In the most simple form:

ExtensionDataBuilder builder = newExtensionDataBuilder();
return builder.addValue(Long.class, 
    builder.valueBuilder("Steps taken") // The text should be different for each value
           .buildNumber(53298L)
);

You can add multiple values to a single builder before returning it.

Here are the types and build methods that are available:

ExtensionDataBuilder builder = newExtensionDataBuilder();

builder.addValue(Boolean.class,  builder.valueBuilder("...").buildBoolean(false));
builder.addValue(Boolean.class,  builder.valueBuilder("...").buildBoolean(() -> false));
// for use with @Conditional on other provider annotations
builder.addValue(Boolean.class,  builder.valueBuilder("...").buildBooleanProvidingCondition(false, "conditionName"));
// for use with @Conditional on other provider annotations
builder.addValue(Boolean.class,     builder.valueBuilder("...").buildBooleanProvidingCondition(() -> false, "conditionName"));
builder.addValue(Long.class,        builder.valueBuilder("...").buildNumber(1234L));
builder.addValue(Long.class,        builder.valueBuilder("...").buildNumber(() -> 1234L));
builder.addValue(Double.class,      builder.valueBuilder("...").buildDouble(500.52));
builder.addValue(Double.class,      builder.valueBuilder("...").buildDouble(() -> 500.52));
builder.addValue(Double.class,      builder.valueBuilder("...").buildPercentage(0.52));
builder.addValue(Double.class,      builder.valueBuilder("...").buildPercentage(() -> 0.52));
builder.addValue(String.class,      builder.valueBuilder("...").buildString("Example"));
builder.addValue(String.class,      builder.valueBuilder("...").buildString(() -> "Example"));
builder.addValue(Component.class,   builder.valueBuilder("...").buildComponent(ComponentService.getInstance().fromAutoDetermine("§eExample")));
builder.addValue(Component.class,   builder.valueBuilder("...").buildComponent(() -> ComponentService.getInstance().fromAutoDetermine("§eExample"))));
builder.addValue(String[].class,    builder.valueBuilder("...").buildGroup(new String[]{"Admin", "Moderator"}));
builder.addValue(String[].class,    builder.valueBuilder("...").buildGroup(() -> new String[]{"Admin", "Moderator"}));
builder.addValue(Table.class,       builder.valueBuilder("...").buildTable(Table.builder()...build(), Color.BLUE));
builder.addValue(Table.class,       builder.valueBuilder("...").buildTable(() -> Table.builder()...build(), Color.BLUE));

return builder;

The lambda methods can be used for method references, conditional values (eg returning null sometimes) and for throwing NotReadyException for a specific value.

Example

@DataBuilderProvider
public ExtensionDataBuilder lotsOfServerData() {
    ExtensionDataBuilder builder = newExtensionDataBuilder();
    return builder.addValue(Long.class, builder.valueBuilder("Houses built")
            .buildNumber(() -> {
                if (database == null) throw new NotReadyException();
                return database.getHouseCount();
            })
        ).addValue(Long.class, builder.valueBuilder("Superheroes")
            .buildNumber(this::getSuperheroCount)
        );

Clean value building example

@DataBuilderProvider
public ExtensionDataBuilder lotsOfServerData() {
    return newExtensionDataBuilder().addValue(Long.class, this::superheroCountValue);
}

private DataValue<Long> superheroCountValue() {
    return valueBuilder("Superheroes")
            .buildNumber(this::getSuperheroCount);
}

private long getSuperheroCount() {
    return 0; // TODO implement later
}

In addition to this value builder has a lot of other methods:

builder.valueBuilder("Example")                                        // 50 char limit
    .description("Describes what Example is about")                    // 150 char limit
    .priority(0)                                                       // ordering priority, highest value is placed top most on the page
    .icon("gavel", Family.SOLID, Color.RED)                            // https://fontawesome.com/icons
    .icon(Icon.called("gavel").of(Family.SOLID).of(Color.RED).build()) // https://fontawesome.com/icons
    .showInPlayerTable()
    .showOnTab("tabName")                                              // remember to add a @TabInfo annotation if using this
    .formatAsDateWithYear()    // for numbers
    .formatAsDateWithSeconds() // for numbers
    .formatAsTimeAmount()      // for numbers
    .format(FormatType.NONE)   // for numbers
    .showAsPlayerPageLink()    // for strings

Adding tables

In addition to the ValueBuilder methods, you can use ExtensionDataBuilder#addTable methods for adding tables dynamically.

ExtensionDataBuilder builder = newExtensionDataBuilder()
    .addTable("table name", Table.builder()...build(), Color.BLUE)
    .addTable("table name", Table.builder()...build(), Color.BLUE, "tabName");

Stuff to avoid

⚠️ Don't define @Conditional with @DataBuilderProvider - it is not supported

@DataBuilderProvider
@Conditional("conditionName") // Throws IllegalArgumentException when registering the extension
public ExtensionDataBuilder lotsOfData(UUID playerUUID) {
}