Skip to content

EXAMPLE_PLUGIN_GUIDE.md

Latest commit

 

History

History
297 lines (230 loc) · 8.11 KB

EXAMPLE_PLUGIN_GUIDE.md

File metadata and controls

297 lines (230 loc) · 8.11 KB

Example Plugin Guide

Overview

The networkdataapi-example-plugin module demonstrates how to create a plugin that leverages NetworkDataAPI's shared MongoDB connection to create and manage its own database collections.

This example shows the CORRECT way to use NetworkDataAPI - as a database connection layer, not an automatic data manager.

What It Demonstrates

1. Shared MongoDB Connection

  • Uses NetworkDataAPI's existing MongoDB connection pool
  • No need to create a separate database connection in your plugin
  • Automatically benefits from connection pooling, caching, and retry logic

2. Isolated Database

  • Creates its own dedicated MongoDB database (example_plugin)
  • Complete data isolation from other plugins
  • No conflicts with other plugin data
  • Each plugin can have its own database!

3. Custom Collections

  • Creates a sample collection (example_collection)
  • Stores documents with custom fields: name, value, timestamp, updated
  • Demonstrates proper collection initialization and indexing

4. CRUD Operations

  • Create: Insert new documents
  • Read: Query documents by name, value, or get all
  • Update: Modify existing documents
  • Delete: Remove documents

5. Performance Optimization

  • Creates indexes on frequently queried fields
  • Uses compound indexes for complex queries
  • Demonstrates MongoDB best practices

6. Comprehensive Logging

  • All operations are logged with detailed information
  • Easy to debug and understand what's happening
  • Helps developers learn MongoDB operations

Directory Structure

networkdataapi-example-plugin/
├── src/main/java/com/astroid/stijnjakobs/networkdataapi/example/
│   ├── ExamplePlugin.java          # Main plugin class
│   ├── ExampleDataManager.java     # MongoDB operations handler
│   └── ExampleCommand.java         # Command handler for testing
├── src/main/resources/
│   └── plugin.yml                  # Plugin configuration
├── pom.xml                         # Maven build configuration
└── README.md                       # Plugin documentation

Key Classes

ExamplePlugin.java

The main plugin class that:

  • Checks for NetworkDataAPI availability
  • Gets the API instance from APIRegistry
  • Creates an isolated database using api.getDatabase("example_plugin")
  • Initializes the data manager
  • Registers commands

Key Code:

// Get API instance
NetworkDataAPIProvider api = APIRegistry.getAPI();

// Get dedicated database for this plugin
MongoDatabase database = api.getDatabase("example_plugin");

ExampleDataManager.java

Manages all MongoDB operations:

  • Collection initialization
  • Index creation for performance
  • Insert, query, update, and delete operations
  • Statistics retrieval
  • Comprehensive operation logging

Key Features:

  • Creates indexes on name and value fields
  • Demonstrates MongoDB filter operations
  • Shows update operations with multiple fields
  • Includes error handling and logging

ExampleCommand.java

In-game command handler that provides:

  • /example insert <name> <value> - Insert a document
  • /example query <name> - Query by name
  • /example queryall - Query all documents
  • /example queryvalue <min> - Query by value
  • /example update <name> <value> - Update a document
  • /example delete <name> - Delete a document
  • /example stats - Show collection statistics

Building the Example Plugin

Prerequisites

  • Maven 3.6+
  • Java 17+
  • Network access to Maven repositories (Spigot/Paper API)

Build Command

cd networkdataapi-example-plugin
mvn clean package

The compiled JAR will be located at:

networkdataapi-example-plugin/target/NetworkDataAPI-Example-1.0-SNAPSHOT.jar

Installation

  1. Install NetworkDataAPI first (prerequisite)
  2. Place NetworkDataAPI-Example-1.0-SNAPSHOT.jar in your plugins/ folder
  3. Start your server
  4. Use /example help to see available commands

Usage Examples

Insert Sample Data

/example insert apple 100
/example insert banana 200
/example insert cherry 50
/example insert orange 150

Query Data

# Query by name
/example query apple

# Query all documents
/example queryall

# Query documents with value > 100
/example queryvalue 100

Update Data

/example update apple 250

Delete Data

/example delete cherry

View Statistics

/example stats

Learning Points

1. How to Get the NetworkDataAPI Instance

import api.com.cynive.networkdataapi.core.APIRegistry;
import api.com.cynive.networkdataapi.core.NetworkDataAPIProvider;

// In your plugin's onEnable()
if (!APIRegistry.isAvailable()) {
    getLogger().severe("NetworkDataAPI not found!");
    getServer().getPluginManager().disablePlugin(this);
    return;
}

NetworkDataAPIProvider api = APIRegistry.getAPI();

2. How to Get Your Own Database

// Get a dedicated database for your plugin
MongoDatabase database = api.getDatabase("your_plugin_name");

3. How to Create Collections

MongoCollection<Document> collection = database.getCollection("your_collection");

4. How to Create Indexes

import com.mongodb.client.model.Indexes;

// Single field index
collection.createIndex(Indexes.ascending("fieldName"));

// Compound index
collection.createIndex(Indexes.ascending("field1", "field2"));

5. How to Insert Documents

import org.bson.Document;

Document doc = new Document()
    .append("name", "example")
    .append("value", 100)
    .append("timestamp", System.currentTimeMillis());

collection.insertOne(doc);

6. How to Query Documents

import com.mongodb.client.model.Filters;

// Query by exact match
Bson filter = Filters.eq("name", "example");
List<Document> results = new ArrayList<>();
collection.find(filter).into(results);

// Query with comparison
Bson filter = Filters.gt("value", 50);
collection.find(filter).into(results);

7. How to Update Documents

import com.mongodb.client.model.Updates;

Bson filter = Filters.eq("name", "example");
Bson update = Updates.combine(
    Updates.set("value", 200),
    Updates.set("updated", true),
    Updates.set("lastModified", System.currentTimeMillis())
);

collection.updateOne(filter, update);

8. How to Delete Documents

Bson filter = Filters.eq("name", "example");
collection.deleteOne(filter);

Benefits of This Approach

✅ No Separate Database Connection

Your plugin doesn't need its own MongoDB connection. Just use NetworkDataAPI's shared connection.

✅ Automatic Connection Management

NetworkDataAPI handles:

  • Connection pooling
  • Automatic reconnection
  • Error retry logic
  • Resource cleanup

✅ Complete Data Isolation

Each plugin can have its own database, preventing conflicts.

✅ Full MongoDB API Access

Use all MongoDB operations without restrictions.

✅ Easy Setup

Just one line of code to get started: api.getDatabase("your_plugin_name")

✅ Better Resource Usage

All plugins share the same connection pool, reducing overhead.

Use Cases

This pattern is perfect for:

  • Cosmetics Plugins: Store owned cosmetics, equipped items
  • Economy Plugins: Store player balances, transactions
  • Guilds/Clans Plugins: Store guild data, members, ranks
  • Stats Plugins: Store player statistics, achievements
  • Punishment Systems: Store bans, mutes, warnings
  • Custom Game Modes: Store game data, player progress

Next Steps

  1. Study the Code: Review each class to understand the implementation
  2. Test It: Run the commands in-game and watch the server logs
  3. Customize It: Adapt the code for your own plugin's needs
  4. Build Your Plugin: Use this as a template for your own database operations

Support

  • Read the main API_DOCUMENTATION.md
  • Review the example plugin's README.md
  • Check the code comments for detailed explanations
  • Open an issue on GitHub for questions

This example plugin is a complete, working reference for building plugins that use NetworkDataAPI!