Class Documentation: JavaStatus

The JavaStatus class is a Java utility for fetching and retrieving the status of a Minecraft Java Edition server using the mcstatus.io API. It provides methods to access various server details such as online status, player count, version, MOTD, mods, plugins, and more.

---

Class Overview

Package

package io.github.undeffineddev.mcstatusio.java;

Class Declaration

public class JavaStatus

---

Constructors

JavaStatus(String address)

Fetches the status of a Java server with default settings (query enabled and a timeout of 5 seconds).

Parameters:

• address (String): The server address (e.g., "example.com" or "192.168.1.1:25565").

Throws:

• IllegalArgumentException: If the server address is null or empty.

• RuntimeException: If an error occurs during the API request.

---

JavaStatus(String address, boolean query, double timeout)

Fetches the status of a Java server with custom query and timeout settings.

Parameters:

• address (String): The server address.

• query (boolean, optional): Whether to query the server for additional details. Defaults to true if not provided.

• timeout (double, optional): The timeout in seconds for the API request. Defaults to 5.0 if not provided.

Throws:

• IllegalArgumentException: If the server address is null or empty.

• RuntimeException: If an error occurs during the API request.

---

Methods

isOnline()

Checks if the server is online.

Returns:

• boolean: true if the server is online, false otherwise.

---

getHost()

Gets the server's host address.

Returns:

• String: The server's host address.

---

getPort()

Gets the server's port.

Returns:

• int: The server's port.

---

getIpAddress()

Gets the server's IP address.

Returns:

• String: The server's IP address, or null if not available.

---

isEulaBlocked()

Checks if the server is blocked due to EULA violations.

Returns:

• boolean: true if the server is EULA blocked, false otherwise.

---

getRetrievedAt()

Gets the timestamp when the data was retrieved.

Returns:

• long: The timestamp in milliseconds.

---

getExpiresAt()

Gets the timestamp when the data expires.

Returns:

• long: The timestamp in milliseconds.

---

getSrvRecord()

Gets the SRV record of the server.

Returns:

• String: The SRV record, or null if not available.

---

getVersionNameRaw()

Gets the raw version name of the server.

Returns:

• String: The raw version name, or null if the server is offline.

---

getVersionNameClean()

Gets the clean version name of the server.

Returns:

• String: The clean version name, or null if the server is offline.

---

getVersionNameHtml()

Gets the HTML version name of the server.

Returns:

• String: The HTML version name, or null if the server is offline.

---

getVersionProtocol()

Gets the protocol version of the server.

Returns:

• int: The protocol version, or -1 if the server is offline.

---

getPlayersOnline()

Gets the number of players currently online.

Returns:

• int: The number of players online, or 0 if the server is offline.

---

getMaxPlayers()

Gets the maximum number of players allowed on the server.

Returns:

• int: The maximum number of players, or 0 if the server is offline.

---

getPlayersList()

Gets the list of players currently online.

Returns:

• JSONArray: A JSONArray of players, or null if the server is offline or no players are online.

---

getPlayerNames()

Gets the list of player names currently online.

Returns:

• ArrayList<String>: A list of player names, or an empty list if the server is offline or no players are online.

---

getPlayerNamesRaw()

Gets the list of player names with formatting.

Returns:

• ArrayList<String>: A list of player names with formatting, or an empty list if the server is offline or no players are online.

---

getMotdRaw()

Gets the raw MOTD (Message of the Day) of the server.

Returns:

• String: The raw MOTD, or null if the server is offline.

---

getMotdClean()

Gets the clean MOTD (Message of the Day) of the server.

Returns:

• String: The clean MOTD, or null if the server is offline.

---

getMotdHtml()

Gets the HTML MOTD (Message of the Day) of the server.

Returns:

• String: The HTML MOTD, or null if the server is offline.

---

getIcon()

Gets the server's icon.

Returns:

• String: The server's icon as a Base64 string, or null if the server is offline or no icon is available.

---

getMods()

Gets the list of mods installed on the server.

Returns:

• JSONArray: A JSONArray of mods, or null if the server is offline or no mods are installed.

---

getModNames()

Gets the list of mod names installed on the server.

Returns:

• ArrayList<String>: A list of mod names, or an empty list if the server is offline or no mods are installed.

---

getModsWithVersions()

Gets the list of mods with their versions.

Returns:

• HashMap<String, String>: A map of mod names to their versions, or an empty map if the server is offline or no mods are installed.

---

getSoftware()

Gets the software running on the server.

Returns:

• String: The server software, or null if the server is offline or no software information is available.

---

getPlugins()

Gets the list of plugins installed on the server.

Returns:

• JSONArray: A JSONArray of plugins, or null if the server is offline or no plugins are installed.

---

getPluginNames()

Gets the list of plugin names installed on the server.

Returns:

• ArrayList<String>: A list of plugin names, or an empty list if the server is offline or no plugins are installed.

---

getPluginsWithVersions()

Gets the list of plugins with their versions.

Returns:

• HashMap<String, String>: A map of plugin names to their versions, or an empty map if the server is offline or no plugins are installed.

---

Usage Example

⚠️ Alert: The JSONArray objects returned by the API contain raw JSON data.

import io.github.undeffineddev.mcstatusio.java;

import org.json.JSONArray;
import java.util.ArrayList;
import java.util.HashMap;

public class Main {
    public static void main(String[] args) {
        // You can change the server address to the one you need to query
        String serverAddress = "play.example.com"; 

        try {
            // Create an instance of JavaStatus (using the default constructor with query=true and timeout=5.0)
            JavaStatus javaStatus = new JavaStatus(serverAddress);

            // Display if the server is online
            System.out.println("Server online: " + javaStatus.isOnline());

            if (javaStatus.isOnline()) {
                // Basic server information
                System.out.println("Host: " + javaStatus.getHost());
                System.out.println("Port: " + javaStatus.getPort());
                System.out.println("IP Address: " + javaStatus.getIpAddress());
                System.out.println("EULA Blocked: " + javaStatus.isEulaBlocked());
                System.out.println("Data retrieved at: " + javaStatus.getRetrievedAt());
                System.out.println("Data expires at: " + javaStatus.getExpiresAt());
                System.out.println("SRV Record: " + javaStatus.getSrvRecord());

                // Version information
                System.out.println("Version (raw): " + javaStatus.getVersionNameRaw());
                System.out.println("Version (clean): " + javaStatus.getVersionNameClean());
                System.out.println("Version (HTML): " + javaStatus.getVersionNameHtml());
                System.out.println("Protocol version: " + javaStatus.getVersionProtocol());

                // Player information
                System.out.println("Players online: " + javaStatus.getPlayersOnline());
                System.out.println("Max players: " + javaStatus.getMaxPlayers());
                JSONArray playersArray = javaStatus.getPlayersList();
                System.out.println("Players list (JSONArray): " + (playersArray != null ? playersArray.toString() : "No players"));
                
                ArrayList<String> playerNames = javaStatus.getPlayerNames();
                System.out.println("Player names: " + playerNames);
                
                ArrayList<String> playerNamesRaw = javaStatus.getPlayerNamesRaw();
                System.out.println("Player names (raw): " + playerNamesRaw);

                // MOTD (Message of the Day) information
                System.out.println("MOTD (raw): " + javaStatus.getMotdRaw());
                System.out.println("MOTD (clean): " + javaStatus.getMotdClean());
                System.out.println("MOTD (HTML): " + javaStatus.getMotdHtml());

                // Server icon
                System.out.println("Icon: " + javaStatus.getIcon());

                // Mods information
                JSONArray modsArray = javaStatus.getMods();
                System.out.println("Mods (JSONArray): " + (modsArray != null ? modsArray.toString() : "No mods"));
                
                ArrayList<String> modNames = javaStatus.getModNames();
                System.out.println("Mod names: " + modNames);
                
                HashMap<String, String> modsWithVersions = javaStatus.getModsWithVersions();
                System.out.println("Mods with versions: " + modsWithVersions);

                // Server software information
                System.out.println("Software: " + javaStatus.getSoftware());

                // Plugins information
                JSONArray pluginsArray = javaStatus.getPlugins();
                System.out.println("Plugins (JSONArray): " + (pluginsArray != null ? pluginsArray.toString() : "No plugins"));
                
                ArrayList<String> pluginNames = javaStatus.getPluginNames();
                System.out.println("Plugin names: " + pluginNames);
                
                HashMap<String, String> pluginsWithVersions = javaStatus.getPluginsWithVersions();
                System.out.println("Plugins with versions: " + pluginsWithVersions);
            } else {
                System.out.println("The server is not online.");
            }
        } catch (Exception e) {
            System.out.println("An error occurred while retrieving the server status: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

---

Notes

• Ensure the server address is valid and reachable.

• The API request may fail if the server is offline or the address is incorrect.

• The query and timeout parameters in the constructor are optional and default to true and 5.0 seconds, respectively.