This page is about API that is available in version 4.8.0 and above.
API can be called on all platforms.

This API requires DATA_EXTENSION_VALUES capability.

See APIv5 for dependency information

• Getting Started with DataExtension API

💭 What is this API for?

DataExtension API is for adding data from your plugin to Plan so that it can be displayed on the Plan website.

• DataExtension API
  • Getting Started
  • 🔔 How to register a DataExtension
  • ℹ️ PluginInfo Annotation
  • 📏 Provider Annotations
  • 🔨 Special Provider Annotations
    • 👥 @GroupProvider
    • 🧰 @DataBuilderProvider, dynamic definition of data at runtime instead of provider annotations
  • 📐 Extra annotations
  • ❕ Preventing runtime errors
    • Implementation violations
  • API in Action

DataExtension API is used for providing Plan with data of your plugin, so that the data can be viewed on the web panel.
This makes it easier for users to reason about their server.

You can follow this step-by-step guide for getting started with the API.

• Getting Started

1. Create a new object that implements DataExtension.
2. Obtain instance of ExtensionService and register using ExtensionService#register(DataExtension)

try {

    DataExtension yourExtension = new YourDataExtensionImplementation();
    ExtensionService.getInstance().register(yourExtension);

} catch (NoClassDefFoundError planIsNotInstalled) {
    // Plan is not installed, handle exception
} catch (IllegalStateException planIsNotEnabled) {
    // Plan is not enabled, handle exception
} catch (IllegalArgumentException dataExtensionImplementationIsInvalid) {
    // The DataExtension implementation has an implementation error, handle exception
}

Registration should be done in it's own class to avoid NoClassDefFoundError if Plan is not installed.
You might need to catch the error when calling your method that does the registering. Getting started, step 2.1

Every DataExtension implementation requires @PluginInfo annotation.

@PluginInfo(
    name = "Your Plugin", // ALWAYS REQUIRED
    iconName = "cube"
    iconFamily = Family.SOLID,
    color = Color.NONE
)
public class YourExtension implements DataExtension {}

• name - Name of your plugin
• iconName - Icon names can be found from https://fontawesome.com/icons?d=gallery&m=free
• iconFamily - Icon family should match details on the site above
• color - Colors are available here Link to be added

Provider annotations are method annotations that tell Plan what kind of data methods in your DataExtension class provide.

The name of the methods are used for storing information the methods provide.

Methods can have 4 different parameters (But only one):

T method();                  // The value is about the server as a whole
T method(UUID playerUUID);   // The value is about a player
T method(String playerName); // The value is about a player
T method(Group group);       // The value is about a Group a player is in

@Override
public CallEvents[] callExtensionMethodsOn() {
    return new CallEvents[]{
           CallEvents.PLAYER_JOIN, 
           CallEvents.PLAYER_PERIODICAL,
           CallEvents.PLAYER_LEAVE,
           CallEvents.SERVER_EXTENSION_REGISTER,
           CallEvents.SERVER_PERIODICAL
    };
}

• DataExtension#callExtensionMethodsOn can be overridden to change default event call behavior (default: PLAYER_JOIN, PLAYER_LEAVE, SERVER_EXTENSION_REGISTER).
• Explanations
  • Empty array: Plan will not call the methods automatically, see below for manual calls.
  • PLAYER_JOIN: Plan calls player methods after a Join event (Bukkit/Bungee: MONITOR, Sponge: POST)
  • PLAYER_PERIODICAL: Plan calls player methods periodically via an async task
  • PLAYER_LEAVE: Plan calls player methods after a Quit event (Bukkit/Bungee: NORMAL, Sponge: DEFAULT)
  • SERVER_EXTENSION_REGISTER Plan calls server methods after registering the DataExtension
  • SERVER_PERIODICAL Plan calls server methods periodically via an async task

DataExtension yourExtension;
Optional<Caller> caller = extensionService.register(yourExtension);

• ExtensionService#register returns a Optional<Caller>. The Caller is present if the extension was registered.
• You can use the Caller methods in your listeners when your data is updated.

HOX Do not use Caller inside DataExtension - This might lead to unbound recursion!

Caller caller;

caller.updatePlayerData(playerUUID, playerName);
caller.updateServerData();

Speciality: boolean values, Can work with @Conditional-annotation for conditional execution

@BooleanProvider(
    text = "Has Island", // ALWAYS REQUIRED
    description = "Whether or not the player has an island in the island world",
    priority = 5,
    iconName = "question",
    iconFamily = Family.SOLID,
    iconColor = Color.NONE,
    conditionName = "islandCondition",
    hidden = false
)
public boolean hasIsland(UUID playerUUID) {...}

• text - Text that appears next to the value, for example "Has Island: No"
• description - Text that appears when hovering over the value
• priority - Ordering number, highest value is placed top most
• iconName - Icon names can be found from https://fontawesome.com/icons?d=gallery&m=free
• iconFamily - Icon family should match details on the site above
• iconColor - Color of the icon that appears next to the value
• conditionName - Name of a condition this boolean represents, used with @Conditional annotations
• hidden - Should this value be hidden from the web panel?

@BooleanProvider(
    ...
    conditionName = "hasIsland"
)
public boolean hasIsland(UUID playerUUID) {
    return true;
}

@Conditional("hasIsland)
@StringProvider(...) // Another provider is required, can be any Provider.
public String islandName(UUID playerUUID) {...}

• conditionName is provided by a @BooleanProvider.
• If the value is true, other methods with @Conditional(conditionName) will be called.
• See Conditional for more

@BooleanProvider(
    ...
    conditionName = "hasLinkedAccount", // REQUIRED to use hidden
    hidden = true
)
public boolean hasLinkedAccount(UUID playerUUID) {...}

• If hidden is true, the conditionName parameter is required.
• "Yes" / "No" for this method will not appear on the web panel.

Speciality: Whole numbers, Time amounts, Timestamps

@NumberProvider(
    text = "Number of Islands", // ALWAYS REQUIRED
    description = "How many islands does the player own",
    priority = 4,
    iconName = "question",
    iconFamily = Family.SOLID,
    iconColor = Color.NONE,
    format = FormatType.NONE
)
public long islandCount(UUID playerUUID) {...}

• text - Text that appears next to the value, for example "Has Island: No"
• description - Text that appears when hovering over the value
• priority - Ordering number, highest value is placed top most
• iconName - Icon names can be found from https://fontawesome.com/icons?d=gallery&m=free
• iconFamily - Icon family should match details on the site above
• iconColor - Color of the icon that appears next to the value
• format - FormatType tells that the value is time amount (milliseconds) or a timestamp

@NumberProvider(
    ...
    format = FormatType.DATE_YEAR
)
public long banDate(UUID playerUUID) {...}

• DATE_YEAR - Value is an Epoch Millisecond, Formats the date based on Plan settings. Year is given importance
• DATE_SECOND - Value is an Epoch Millisecond, Formats the date based on Plan settings. Seconds are given importance
• TIME_MILLISECOND - Value is amount of milliseconds, Formats time amount based on Plan settings.
• NONE - Value is not formatted

Speciality: Floating point numbers

@DoubleProvider(
    text = "Balance", // ALWAYS REQUIRED
    description = "Amount of money the player has",
    priority = 3,
    iconName = "question",
    iconFamily = Family.SOLID,
    iconColor = Color.NONE
)
public double balance(UUID playerUUID) {...}

• text - Text that appears next to the value, for example "Has Island: No"
• description - Text that appears when hovering over the value
• priority - Ordering number, highest value is placed top most
• iconName - Icon names can be found from https://fontawesome.com/icons?d=gallery&m=free
• iconFamily - Icon family should match details on the site above
• iconColor - Color of the icon that appears next to the value

Speciality: Percentages between 0% and 100%. Requires return values between 0.0 and 1.0.

@PercentageProvider(
    text = "Quest completion", // ALWAYS REQUIRED
    description = "Quest completion percentage",
    priority = 5,
    iconName = "question",
    iconFamily = Family.SOLID,
    iconColor = Color.NONE
)
public double questCompletion(UUID playerUUID) {...}

• text - Text that appears next to the value, for example "Has Island: No"
• description - Text that appears when hovering over the value
• priority - Ordering number, highest value is placed top most
• iconName - Icon names can be found from https://fontawesome.com/icons?d=gallery&m=free
• iconFamily - Icon family should match details on the site above
• iconColor - Color of the icon that appears next to the value

Speciality: String values, Links to player page when playerName is true

@StringProvider(
    text = "Town Name", // ALWAYS REQUIRED
    description = "What town the player has residency in.",
    priority = 5,
    iconName = "question",
    iconFamily = Family.SOLID,
    iconColor = Color.NONE,
    playerName = false
)
public String townName(UUID playerUUID) {...}

• text - Text that appears next to the value, for example "Has Island: No"
• description - Text that appears when hovering over the value
• priority - Ordering number, highest value is placed top most
• iconName - Icon names can be found from https://fontawesome.com/icons?d=gallery&m=free
• iconFamily - Icon family should match details on the site above
• iconColor - Color of the icon that appears next to the value
• playerName - Does this provider return a player name that can be linked to? Links are automatic

@StringProvider(
    ...
    playerName = true
)
public String townMayor(Group town) {...}

• If playerName is true, the returned value will be formatted to display a link to a player's page.

Speciality: String values that have chat colors in them (legacy / bungee / minimessage)

@ComponentProvider(
    text = "Display name", // ALWAYS REQUIRED
    description = "What name is the player using",
    priority = 5,
    iconName = "question",
    iconFamily = Family.SOLID,
    iconColor = Color.NONE
)
public Component displayName(UUID playerUUID) {
    return ComponentService.getInstance().fromAutoDetermine(... /* Put the string in here */);
}

• text - Text that appears next to the value, for example "Has Island: No"
• description - Text that appears when hovering over the value
• priority - Ordering number, highest value is placed top most
• iconName - Icon names can be found from https://fontawesome.com/icons?d=gallery&m=free
• iconFamily - Icon family should match details on the site above
• iconColor - Color of the icon that appears next to the value

These annotations can be used to add information structures. They might have different limitations than other providers.

Speciality: Multiple Groups the player is in. Any providers with Group parameter will be called with the groups that this method provides (Not implemented yet).

• Requires DATA_EXTENSION_GROUPS capability

• Method requires UUID or String as method parameter.
• Group names over 50 characters will be truncated

Plan will construct following from given group data:

• Players in different groups are counted

@GroupProvider(
    text = "Jobs", // ALWAYS REQUIRED
    groupColor = Color.NONE
    iconName = "question",
    iconFamily = Family.SOLID,
)
public String[] playerJobs(UUID playerUUID) {
    return new String[]{"Mason", "Woodcutter"}
}

• text - Text that appears next to the value, for example "Jobs: None"
• groupColor - Color of the icon or table that appears near the groups
• iconName - Icon names can be found from https://fontawesome.com/icons?d=gallery&m=free
• iconFamily - Icon family should match details on the site above

Speciality: Table structures.

• Requires DATA_EXTENSION_TABLES capability

• Player tables can have 4 columns.
• Server tables can have 5 columns.
• Values can only be 50 characters long when toString() is applied.

If you want to display a table that lists how many players are using something (or data about groups), eg. Players on each version, use @GroupProvider (and Group parameter methods) instead.

@TableProvider(tableColor = Color.NONE)
public Table banHistory(UUID playerUUID) {
    Table.Factory banTable = Table.builder()
            .columnOne("When", new Icon(Family.SOLID, "gavel")) // Define column names and icons
            .columnOneFormat(TableColumnFormat.DATE_SECOND) // All columns support formatting similar to other Providers (numbers, strings)
            .columnTwo("...", new Icon(...)) // Icon colors are ignored.
            .columnThree("...", new Icon(...))
            .columnFour("...", new Icon(...));

    for (YourData data : yourData) {
        banTable.addRow(System.currentTimeMillis(), true, "Reason", "...");
    }

    return banTable.build();
}

• tableColor - Color of the table header.

Speciality: Dynamic definition of providers at runtime.

• Requires DATA_EXTENSION_BUILDER_API capability

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

• More about builder API here

Speciality: Graphs.

This will be implemented later.

These annotations can be used to further control how the values are displayed.

Specialilty: Control what plugin-tab the provided value appears in.

@TabInfo(
    tab = "Economy", // REQUIRED
    iconName = "circle",
    iconFamily = Family.SOLID,
    elementOrder = {ElementOrder.VALUES, ElementOrder.TABLE, ElementOrder.GRAPH}
)
@TabInfo(tab = "Second Tab") // REQUIRED
@TabOrder({"Economy", "Second Tab"})
@PluginInfo(...)
public class YourExtension implements DataExtension {

    @BooleanProvider(text = "Has Pet")
    @Tab("Second Tab")
    public boolean hasPet(UUID playerUUID) {...}

}

• tab - Name of the tab
• iconName - Icon names can be found from https://fontawesome.com/icons?d=gallery&m=free
• iconFamily - Icon family should match details on the site above
• elementOrder - Order different elements are placed inside the tab. VALUES represents all single values

Specialilty: Control execution of another methods. If provided boolean is true the method with @Conditional annotation will be called.

@BooleanProvider(..., conditionName="hasPet")
public boolean hasPet(UUID playerUUID) {...}

@Conditional("hasPet")
@StringProvider(text = "Pet Name")
public String petName(UUID playerUUID) {...}

• value - Name of the condition
• negated - Require the condition to be false for this method to be called.

@BooleanProvider(..., conditionName="permanentBan")
public boolean isPermanentlyBanned(UUID playerUUID) {...}

@Conditional(value = "permanentBan", negated = true)
@NumberProvider(...)
public long expiryDate(UUID playerUUID) {...}

• Negated Conditionals are only called when the provided condition is false.

@BooleanProvider(..., conditionName="isBanned")
public boolean isBanned(UUID playerUUID) {...}

@Conditional("isBanned")
@BooleanProvider(..., conditionName="isTemporaryBan")
public boolean isTemporaryBan(UUID playerUUID) {...}

@Conditional("isTemporaryBan")
@NumberProvider(...)
public long expireDate(UUID playerUUID) {...}

• Conditions can be nested by adding a @Conditional @BooleanProvider that returns a second condition.

Speciality: Removes old values from database if you decide to rename a method. The method name is used when storing the values, so this annotation exists to remove the old values.

@InvalidateMethod("oldMethodName")
@PluginInfo(...)
public class YourExtension implements DataExtension {
   @BooleanProvider(...)
   public boolean newMethodName(UUID playerUUID) {...}
}

• value - Name of a removed method, for removing stored results of that method.

Since annotations do not have any compiler checks, invalid implementation can not be enforced at compile time, and runtime exceptions are used instead.

To make implementation easier it is possible to Unit test against the implementation errors.

How:

@Test
public void noImplementationErrors() {
    DataExtension yourExtension = new YourExtensionImplementation();

    // Throws IllegalArgumentException if there is an implementation error or warning.
    new ExtensionExtractor(yourExtension).validateAnnotations();
}

Here is a short list of what throws an exception

• No @PluginInfo class annotation
• Class contains no public methods with Provider annotations
• Class contains private method with Provider annotation
• Non-primitive return type when primitive is required (eg. Boolean instead of boolean)
• Method doesn't have correct parameters (none, UUID, String or Group)
• @BooleanProvider is annotated with a @Conditional that requires same condition the provider provides.
• @Conditional without a @BooleanProvider that provides value for the condition

Warnings:

• An annotation String <variable> is over 50 characters (Or over 150 if description)
• Method name is over 50 characters (Used as an identifier for storage)

If you would like to see how the API is being used in built in plugin support, check out implementations in repositories that start with Extension

ExtensionFactory classes are not important, since they are used by Plan for creating the DataExtension instances when Plan enables. The registration is not automatic.