Providers — LunaDeerMC

Why use providers

DominionDTO, GroupDTO, and MemberDTO expose some set... methods, but addons should not use them to bypass Dominion’s business flow. Providers perform permission, boundary, economy, and data-consistency checks before writing, then fire the corresponding events.

All data-operation providers return CompletableFuture. A completion value of null usually means that Dominion rejected the operation or it failed. The teleport provider uses Boolean for success. Handle null and use exceptionally to record unexpected exceptions.

The `operator` identity

The operation methods of DominionProvider, GroupProvider, MemberProvider, and CopyProvider all take a CommandSender operator parameter:

pass a Player to execute as that player; Dominion checks whether the player has the relevant claim permission;
pass Bukkit.getConsoleSender() for a backend/console operation; this bypasses player permission checks but not basic validity checks such as names, boundaries, and database state;
do not replace an ordinary player with the console to hide the permission model. The addon should make it explicit when the server administrator authorizes the operation.

DominionProvider

Entry point: DominionAPI.getDominionProvider().

Method	Purpose
`createDominion(operator, name, owner, world, cuboid, parent, skipEconomy)`	Create a top-level claim or child claim
`resizeDominion(operator, dominion, type, direction, size)`	Expand or contract a claim in a direction
`deleteDominion(operator, dominion, skipEconomy, force)`	Delete a claim; control whether child claims are force-deleted
`renameDominion(operator, dominion, newName)`	Rename a claim
`transferDominion(operator, dominion, newOwner, force)`	Transfer ownership of a top-level claim
`setDominionTpLocation(operator, dominion, location)`	Change the teleport point
`setDominionMessage(operator, dominion, type, message)`	Change the entry/exit message
`setDominionMapColor(operator, dominion, color)`	Change the map display color
`setDominionEnvFlag(operator, dominion, flag, value)`	Change a claim environment flag
`setDominionGuestFlag(operator, dominion, flag, value)`	Change a guest permission flag

When parent is null, createDominion creates a top-level claim. skipEconomy only skips the economy check or charge; it does not skip every restriction. resizeDominion uses the DominionReSizeEvent.TYPE and DIRECTION enums. Directions include NORTH, SOUTH, EAST, WEST, UP, and DOWN.

deleteDominion(operator, dominion, skipEconomy) and transferDominion(operator, dominion, newOwner) are convenience overloads whose default force is true. High-risk addon features should pass the complete argument list explicitly to avoid accidental deletion or transfer.

GroupProvider

Entry point: DominionAPI.getGroupProvider().

Method	Purpose
`createGroup(operator, dominion, groupName)`	Create a group
`deleteGroup(operator, dominion, group)`	Delete a group; its members leave the group
`renameGroup(operator, dominion, group, newName)`	Rename a group
`setGroupFlag(operator, dominion, group, flag, value)`	Change a group permission flag
`addMember(operator, dominion, group, member)`	Add a member to a group
`removeMember(operator, dominion, group, member)`	Remove a member from a group

Group permissions and a member’s own permissions are separate sources. Removing a member from a group removes only the permissions provided by the group; permissions set directly on the member remain in the MemberDTO.

MemberProvider

Entry point: DominionAPI.getMemberProvider().

Method	Purpose
`addMember(operator, dominion, player)`	Add a player as a claim member
`removeMember(operator, dominion, member)`	Remove a member and its group relationships in the claim
`setMemberFlag(operator, dominion, member, flag, value)`	Change an individual member permission flag

Before adding a member, obtain the PlayerDTO with api.getPlayer(UUID). An online Bukkit Player and a Dominion PlayerDTO are different types.

Other providers

Provider	Common methods	Description
`PlayerProvider`	`getKnownPlayers()`, `getAvailableGroupTitles(UUID)`, `setGroupTitle(Player, GroupDTO)`	Player profiles and display group titles
`TeleportProvider`	`teleport(Player, DominionDTO)`	Dominion’s local/cross-server teleport flow; returns `CompletableFuture<Boolean>`
`TemplateProvider`	`getTemplates`, `createTemplate`, `setTemplateFlag`, `applyTemplate`	Permission templates owned by a player
`CopyProvider`	`copy(operator, source, target, CopyType)`	Copy selected management data between claims

CopyType includes ENVIRONMENT, GUEST, MEMBER, and GROUP. Copying includes existing claim configuration and member data. Addons should provide an explicit configuration switch and remind administrators to back up before running it in production.

Handle asynchronous results correctly

DominionAPI api = DominionAPI.getInstance();
DominionDTO result = null;

api.getDominionProvider()
        .renameDominion(Bukkit.getConsoleSender(), dominion, "new-name")
        .thenAccept(updated -> {
            if (updated == null) {
                getLogger().warning("Dominion rename was rejected.");
                return;
            }
            getLogger().info("Renamed dominion to " + updated.getName());
        })
        .exceptionally(error -> {
            getLogger().severe("Dominion operation failed: " + error.getMessage());
            return null;
        });

Do not read the result variable immediately after the asynchronous call; the Future has not completed. Never call future.get() or future.join() on the Bukkit main thread or a Folia region thread. If a callback needs to operate on an entity, interface, or world, switch back to the target server scheduler and follow the Paper/Folia threading model.