snapshot-lib

A Java library for communicating with the snapshot API.

🧲 Quick navigation

1. 📚 Information
2. 📋 Requirements
3. 📥 Project Setup
4. 🖊️ Building a ServerLog
5. 🔨 Handling a ServerLog
6. 📕 References

📚 Information

This library simplifies communication with snapshot servers by adding multiple specialized methods.

Snapshot is a Spring Boot application for collecting and viewing Minecraft server debug information. It provides a REST API for log uploads and a simple web interface for searching and viewing logs.

📋 Requirements

• Java 17 or higher
• Maven 3.6+ if you want to compile the project

📥 Project Setup

Maven

<repositories>
  <repository>
    <id>myth-mc-releases</id>
    <name>myth-MC Repository</name>
    <url>https://repo.mythmc.ovh/releases</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>ovh.mythmc</groupId>
    <artifactId>snapshot-lib</artifactId>
    <version>VERSION</version>
  </dependency>
</dependencies>

Gradle Kotlin

repositories {
    maven {
        name = "mythmc"
        url = uri("https://repo.mythmc.ovh/releases")
    }
}

dependencies {
    implementation("ovh.mythmc:snapshot-lib:VERSION")
}

Gradle Groovy

repositories {
    maven {
        name = 'mythmc'
        url = 'https://repo.mythmc.ovh/releases'
    }
}

dependencies {
    implementation 'ovh.mythmc:snapshot-lib:VERSION'
}

🖊️ Building a ServerLog

A ServerLog contains all the information that will be sent to the server. You may build one by using ServerLogBuilder, which can be instantiated with ServerLog.builder(). Here's a basic implementation will all the necessary fields:

ServerLog log = ServerLog.builder()
    .requester("Requester")
    .pluginName("MyPlugin")
    .pluginVersion("1.0.0")
    .serverPort(Bukkit.getPort())
    .serverVersion(Bukkit.getVersion())
    .serverSoftware(Bukkit.getName())
    .onlineMode(Bukkit.getOnlineMode())
    .build();

📋 Adding extra fields

snapshot supports an extra field which can be used to include additional data such as text files or basic objects as long as they can be serialized with GSON:

ServerLog log = ServerLog.builder()
    // ...
    .addExtra("extraString", "This is an extra string!")
    // ...

To send text files, they must be converted into a Base64 string first.

🔨 Handling a ServerLog

Once we have a ServerLog, we can proceed to handle it. This is the part where the log will be sent to a snapshot server - which we can conveniently configure. To do so, we'll use the ServerLogHandler class, which is instantiated with a builder as well.

Building a ServerLogHandler

// The handler needs to know how to serialize our ServerLog.
// Snapshot servers only support JSON for now, so we'll use GsonServerLogSerializer.
ServerLogSerializer serializer = GsonServerLogSerializer.get();

// Once the information is serialized, the handler will transfer it.
// We use HttpServerLogTransport for that.
String endpoint = "https://debug.mythmc.ovh/api/v1/upload"; // You can change this to your desired endpoint
ServerLogTransport transport = new HttpServerLogTransport(endpoint);

// Lastly, the handler needs to know how to process the information received from the server.
// ServerLogResponseParser will take care of this.
ServerLogResponseParser responseParser = ServerLogResponseParser.get();

ServerLogHandler handler = ServerLogHandler.builder()
    .provider(log)
    .serializer(serializer)
    .transport(transport)
    .responseParser(responseParser)
    .build();

Sending the data

Now that our handler is properly built and configured, we can proceed to send the data to the specified endpoint:

handler.handleAsync().thenAccept(result -> {
  // Our result is an instance of ServerLogHandleResult, which contains the information that the server gave us.

  // Let's get the log ID (debug code) and print it:
  String logId = result.parsedResponse().get().logId().get();
  System.out.println("Debug code: " + logId);
});

Warning

You should always use ServerLogHandler#handleAsync in production. For development purposes, ServerLogHandler#handle is available too.

📕 References

• This is a Java library that interacts with a snapshot server