16
DataExtension API Getting started
Aurora Lahtela edited this page 2022-10-30 11:27:41 +02:00
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 inpom.xmlof your project
<repository>
<id>jitpack</id>
<url>https://jitpack.io</url>
</repository>
Gradle
- Add the repository to your
repositories-block inbuild.gradleof 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 inpom.xmlof 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 inbuild.gradleof 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
softdependinplugin.ymlof your project
softdepend:
- Plan
# nukkit
softdepend: ["Plan"]
# bungee
softDepends:
- Plan
Sponge & Velocity (Plugin annotation)
- Add Plan as an optional dependency to the
@Pluginannotation
@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:
import com.djrapitops.plan.capability.CapabilityService;
import com.djrapitops.plan.extension.ExtensionService;
public class PlanHook {
private final MyPluginDatabase database; // Replace with whatever you use to store your plugin's data
public PlanHook(MyPluginDatabase database) {
this.database = database;
}
public void hookIntoPlan() {
if (!areAllCapabilitiesAvailable()) return;
registerDataExtension();
listenForPlanReloads();
}
private boolean areAllCapabilitiesAvailable() {
CapabilityService capabilities = CapabilityService.getInstance();
return capabilities.hasCapability("DATA_EXTENSION_VALUES");
}
private void registerDataExtension() {
try {
ExtensionService.getInstance().register(new MyPluginDataExtension(database));
} catch (IllegalStateException planIsNotEnabled) {
// Plan is not enabled, handle exception
} catch (IllegalArgumentException dataExtensionImplementationIsInvalid) {
// The DataExtension implementation has an implementation error, handle exception
}
}
private void listenForPlanReloads() {
CapabilityService.getInstance().registerEnableListener(
isPlanEnabled -> {
// Register DataExtension again
if (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
private final MyPluginDatabase database; // Replace with whatever you use to store your plugin's data
public PlanHook(MyPluginDatabase database) {
this.database = database;
}
MyPluginDatabaseis the database of the example plugin, and is given so that the DataExtension has some data to display later.
hookIntoPlan()
public void hookIntoPlan() {
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()
private boolean areAllCapabilitiesAvailable() {
CapabilityService capabilities = CapabilityService.getInstance();
return capabilities.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()
private void registerDataExtension() {
try {
ExtensionService.getInstance().register(new MyPluginDataExtension(database));
} catch (IllegalStateException planIsNotEnabled) {
// Plan is not enabled, handle exception
} catch (IllegalArgumentException dataExtensionImplementationIsInvalid) {
// The DataExtension implementation has an implementation error, handle exception
}
}
- Creates
MyPluginDataExtensionwith the database of the plugin, and registers it to Plan IllegalStateExceptionmight be thrown if Plan has not enabled properlyIllegalArgumentExceptionmight be thrown if theMyPluginDataExtensionhas an implementation error. Later a test class is created to avoid this issue.
listenForPlanReloads()
private void listenForPlanReloads() {
CapabilityService.getInstance().registerEnableListener(
isPlanEnabled -> {
// Register DataExtension again
if (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
MyPluginDatabase database; // Replace with whatever you use to store your plugin's data
public void onEnable() {
... // The example plugin enables itself
try {
new PlanHook(database).hookIntoPlan();
} catch (NoClassDefFoundError planIsNotInstalled) {
// 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
)
public class MyPluginDataExtension implements DataExtension {
private final MyPluginDatabase database; // Replace with whatever you use to store your plugin's data
public MyPluginDataExtension(MyPluginDatabase database) {
this.database = database;
}
@Override
public CallEvents[] callExtensionMethodsOn() {
return new CallEvents[]{
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
)
public long challengesCompleted(UUID playerUUID) {
return database.getCompletedChallengeCount(playerUUID);
}
}
Individual sections explained:
PluginInfo annotation
@PluginInfo(
name = "MyPlugin",
iconName = "vial",
iconFamily = Family.SOLID,
color = Color.LIGHT_BLUE
)
public class MyPluginDataExtension implements DataExtension {...}
- 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
private final MyPluginDatabase database; // Replace with whatever you use to store your plugin's data
public MyPluginDataExtension(MyPluginDatabase database) {
this.database = database;
}
MyPluginDatabaseis the database of the example plugin, and is given so that the DataExtension has some data to display.
Overriding callExtensionMethodsOn
@Override
public CallEvents[] callExtensionMethodsOn() {
return new CallEvents[]{
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
)
public long challengesCompleted(UUID playerUUID) {
return database.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,
NumberProviderrequireslongto 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.
@Test
public void noImplementationErrors() {
DataExtension yourExtension = new MyPluginExtension();
// Throws IllegalArgumentException if there is an implementation error or warning.
new ExtensionExtractor(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