DataExtension API Builders

DataExtension API - Builders

DataExtension Builder APIs require DATA_EXTENSION_BUILDER_API capability.

---

🧰 @DataBuilderProvider annotation

Speciality: Dynamic definition of providers at runtime.

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")
           .buildNumber(53298L)
);

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

Here are the types and build methods that are available:

builder.addValue(Boolean.class, builder.valueBuilder("Example").buildBoolean(false));

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

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)
        );

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 @TabInfo annotation
    .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) {
}