DataExtension API Getting started

DataExtension API - Getting started

This tutorial attempts to guide you through adding a DataExtension to your plugin, for more in-depth documentation about different parts of the API, see DataExtension API.

These icons are used to aid understanding

💭 Question about possible issues (Someone has had these before)
💡 Extra stuff

✔️ Requirements

• A java plugin project for a minecraft server

🚩 Tutorial Goals

Here are the goals the tutorial aims to guide you through.
At the end of this tutorial you will have

• .. Added Plan API as a dependency to your project
  • (.. added Plan as soft-dependency to your plugin)
• .. Created 2 new classes to use the API
• .. Created 1 new test class to test use of the API
• .. Defined a DataExtension that adds a number to a player's page

💭 What is this API for?

DataExtension API is for displaying data from a plugin on the Plan website.

---

Goal #1: Adding Plan API as a dependency

1.1: Add Plan repository to your project

Maven

• Add the repository to your <repositories>-block in pom.xml of your project

<repository>
<id>jitpack</id>
<url>https://jitpack.io</url>
</repository>

Gradle

• Add the repository to your repositories-block in build.gradle of your project

maven {
url "https://jitpack.io" }

Other build tools

• Add Plan API as a dependency in your build tool. (you can download it from here https://github.com/plan-player-analytics/Plan/releases)

1.2: Add Plan API as a dependency

• Go to https://github.com/plan-player-analytics/Plan/tags and see what is the latest version number. No need to download anything.

Maven

• Add Plan API as a dependency to your <dependencies>-block in in pom.xml of your project

<dependency>
<groupId>com.github.plan-player-analytics</groupId>
<artifactId>Plan</artifactId>
<version>{jitpack version}</version> <!-- Add the version number here -->
<scope>provided</scope>
</dependency>

Gradle

• Add Plan API as a compile & test compile time dependency to your dependencies-block in build.gradle of your project.

compileOnly 'com.github.plan-player-analytics:Plan:{jitpack version}'
testCompileOnly 'com.github.plan-player-analytics:Plan:{jitpack version}'

Other

• Add Plan as a dependency in your build tool. (you can download it from here https://github.com/plan-player-analytics/Plan/releases)

1.3: Add Plan as a soft-dependency in your plugin

Spigot, Nukkit & Bungeecord (plugin.yml)

• Add Plan in softdepend in plugin.yml of your project

softdepend:
- Plan# nukkitsoftdepend: ["Plan"]# bungeesoftDepends:
- Plan

Sponge & Velocity (Plugin annotation)

• Add Plan as an optional dependency to the @Plugin annotation

@Plugin(
id = ...,
dependencies = {
@Dependency(id ="plan", optional =true)
}
)

✔️ Your project now includes Plan API as a dependency!

Goal #2: Access Plan API from your plugin

2.1: Create a class to separate Plan imports from your main class

In order to keep Plan as an optional dependency, all access to the Plan API should be made from a separate class. In this tutorial this will be called PlanHook, but you can call it whatever you want.

Let's take a look at this example class:

importcom.djrapitops.plan.capability.CapabilityService;
importcom.djrapitops.plan.extension.ExtensionService;
publicclassPlanHook {
privatefinalMyPluginDatabasedatabase; // Replace with whatever you use to store your plugin's datapublicPlanHook(MyPluginDatabasedatabase) {
this.database = database;
}
publicvoidhookIntoPlan() {
if (!areAllCapabilitiesAvailable()) return;
registerDataExtension();
listenForPlanReloads();
}
privatebooleanareAllCapabilitiesAvailable() {
CapabilityServicecapabilities = CapabilityService.getInstance();
returncapabilities.hasCapability("DATA_EXTENSION_VALUES");
}
privatevoidregisterDataExtension() {
try {
ExtensionService.getInstance().register(newMyPluginDataExtension(database));
} catch (IllegalStateExceptionplanIsNotEnabled) {
// Plan is not enabled, handle exception
} catch (IllegalArgumentExceptiondataExtensionImplementationIsInvalid) {
// The DataExtension implementation has an implementation error, handle exception
}
}
privatevoidlistenForPlanReloads() {
CapabilityService.getInstance().registerEnableListener(
isPlanEnabled -> {
// Register DataExtension againif (isPlanEnabled) registerDataExtension();
}
);
}
}

Creating a separate class is necessary to keep NoClassDefFoundError away from loading your plugin when Plan is not enabled!

Here is some more explanation for each section of the code in case you need more information.

Construction

privatefinalMyPluginDatabasedatabase; // Replace with whatever you use to store your plugin's datapublicPlanHook(MyPluginDatabasedatabase) {
this.database = database;
}

• MyPluginDatabase is the database of the example plugin, and is given so that the DataExtension has some data to display later.

hookIntoPlan()

publicvoidhookIntoPlan() {
if (!areAllCapabilitiesAvailable()) return;
registerDataExtension();
listenForPlanReloads();
}

• This method checks if Plan has the capabilities you need, the check is similar to how some plugins ask you to check the version number.
• If the capabilities are available, the extension is registered.
• Additionally a listener for Plan reloads is registered to re-register the data extension.

areAllCapabilitiesAvailable()

privatebooleanareAllCapabilitiesAvailable() {
CapabilityServicecapabilities = CapabilityService.getInstance();
returncapabilities.hasCapability("DATA_EXTENSION_VALUES");
}

• Checks that DATA_EXTENSION_VALUES capability is available. Some features might need more capabilities, and when they do it is mentioned in the documentation. Those capabilities can then be added here.

registerDataExtension()

privatevoidregisterDataExtension() {
try {
ExtensionService.getInstance().register(newMyPluginDataExtension(database));
} catch (IllegalStateExceptionplanIsNotEnabled) {
// Plan is not enabled, handle exception
} catch (IllegalArgumentExceptiondataExtensionImplementationIsInvalid) {
// The DataExtension implementation has an implementation error, handle exception
}
}

• Creates MyPluginDataExtension with the database of the plugin, and registers it to Plan
• IllegalStateException might be thrown if Plan has not enabled properly
• IllegalArgumentException might be thrown if the MyPluginDataExtension has an implementation error. Later a test class is created to avoid this issue.

listenForPlanReloads()

privatevoidlistenForPlanReloads() {
CapabilityService.getInstance().registerEnableListener(
isPlanEnabled -> {
// Register DataExtension againif (isPlanEnabled) registerDataExtension();
}
)
}

• Registers a listener to Plan that registers the extension again in case Plan is reloaded.

2.2: Construct and call the PlanHook in your plugin enable.

In this example the Spigot JavaPlugin#onEnable is used, but you can add these methods to wherever you wish, as long as it is called after Plan has been loaded & enabled.

💭 When does Plan enable?

• Spigot & Nukkit: After dependencies have enabled & worlds have been loaded
• Sponge: After dependencies on GameStartedServerEvent
• BungeeCord: After dependencies
• Velocity: After dependencies on ProxyInitializeEvent

MyPluginDatabasedatabase; // Replace with whatever you use to store your plugin's datapublicvoidonEnable() {
... // The example plugin enables itselftry {
newPlanHook(database).hookIntoPlan();
} catch (NoClassDefFoundErrorplanIsNotInstalled) {
// Plan is not installed
}
}

✔️ You can now access Plan API from somewhere!

Goal #3: Creating a DataExtension

You might have noticed that there was a MyPluginDataExtension in the previous section, this is what is going to be implemented next.

3.1: Create your DataExtension class

Let's look at this example class:

@PluginInfo(
name = "MyPlugin", iconName = "vial", iconFamily = Family.SOLID, color = Color.LIGHT_BLUE
)
publicclassMyPluginDataExtensionimplementsDataExtension {
privatefinalMyPluginDatabasedatabase; // Replace with whatever you use to store your plugin's datapublicMyPluginDataExtension(MyPluginDatabasedatabase) {
this.database = database;
}
@OverridepublicCallEvents[] callExtensionMethodsOn() {
returnnewCallEvents[]{
CallEvents.PLAYER_JOIN,
CallEvents.PLAYER_LEAVE
};
}
@NumberProvider(
text = "Completed Challenges",
description = "How many challenges has the player completed",
iconName = "bookmark",
iconColor = Color.GREEN,
priority = 100,
showInPlayerTable = true
)
publiclongchallengesCompleted(UUIDplayerUUID) {
returndatabase.getCompletedChallengeCount(playerUUID);
}
} 

Individual sections explained:

PluginInfo annotation

@PluginInfo(
name = "MyPlugin", iconName = "vial", iconFamily = Family.SOLID, color = Color.LIGHT_BLUE
)
publicclassMyPluginDataExtensionimplementsDataExtension {...}

• PluginInfo annotation provides meta-data to Plan on how to display your plugin on the page.
• It is a class annotation, the class needs to implement DataExtension
• Documentation (middle-click to open to new tab)

Construction

privatefinalMyPluginDatabasedatabase; // Replace with whatever you use to store your plugin's datapublicMyPluginDataExtension(MyPluginDatabasedatabase) {
this.database = database;
}

• MyPluginDatabase is the database of the example plugin, and is given so that the DataExtension has some data to display.

Overriding callExtensionMethodsOn

@OverridepublicCallEvents[] callExtensionMethodsOn() {
returnnewCallEvents[]{
CallEvents.PLAYER_JOIN,
CallEvents.PLAYER_LEAVE
};
}

• This method determines when Plan calls the Provider methods you declare in your DataExtension. You might need to change this depending on what kind of methods you put in. Forcing updates is also possible.
• Documentation (controlling when Plan calls your DataExtension methods) (middle-click to open to new tab)

NumberProvider and challengesCompleted method

@NumberProvider(
text = "Completed Challenges",
description = "How many challenges has the player completed",
iconName = "bookmark",
iconColor = Color.GREEN,
priority = 100,
showInPlayerTable = true
)
publiclongchallengesCompleted(UUIDplayerUUID) {
returndatabase.getCompletedChallengeCount(playerUUID);
}

• Provider annotations give meta-data to Plan on how to display the data you are about to give, such as name, description, where to show it on the page etc.
• Each provider annotation needs specific return type, NumberProvider requires long to be returned.
• The method parameters determine if the method is a "Player method" or "Server method", in this case UUID -> This is a player method
• Documentation for NumberProvider (middle-click to open to new tab)
• Documentation for all Provider annotations (middle-click to open to new tab)

✔️ You now have a DataExtension!

Goal #4: Test your DataExtension implementation

Place a test method to a test class.

@TestpublicvoidnoImplementationErrors() {
DataExtensionyourExtension = newMyPluginExtension();
// Throws IllegalArgumentException if there is an implementation error or warning.newExtensionExtractor(yourExtension).validateAnnotations();
}

✔️ Less errors at runtime!

---

There is still a lot of additional annotations to further control the meta-data and for different kinds of data. I'll list some here for you to check out from the DataExtension API documentation

• Providers
  • BooleanProvider: Yes/No answers and possibility for conditional data
  • NumberProvider: Numbers, time amounts and dates.
  • DoubleProvider: Floating point numbers
  • PercentageProvider: Percentages between 0% and 100%
  • StringProvider: Strings and player names that link to the player's page
  • GroupProvider: Names of different groups the player belongs in, eg. Permission groups
  • TableProvider: Data for displaying a table
• Extra annotations
  • Tab, TabInfo and TabOrder: Place provided data to different sections on the page (For cases like where your plugin provides lots of different kinds of data, such as an Essentials or punishment plugin)
  • Conditional: Controls conditional execution of the provider method
  • InvalidateMethod: If you remove a extension method later this annotation is used to remove the old data