Package com.ultikits.ultitools.utils
package com.ultikits.ultitools.utils
-
ClassDescriptionImplements persist-id, acknowledge, then execute for ack-first requests.The operator's switches as UltiCloud protocol capabilities (plan 22-21, S-65, S-66).The reconnect state machine of the UltiCloud v2 agent connection (as of 6.3.1).What a refusal or a close means for the connection.One attempt's socket, as the state machine sees it.Callbacks to the owner (the cloud session).What
AgentConnection.reconnectNow()did.Events of one attempt's socket; each instance is bound to one attempt id.Opens one attempt's socket; must not block.The states of the connection.The connection's timers.Derives the UltiCloud agent WebSocket endpoint from the build-time API URL (as of 6.3.1).Validates envelopes and dispatches framework handlers; internal, not for module use.Hears every request the capability gate refused because the operator's switch (or the handshake) does not allow it, after its correlatedcapability_not_acceptedreply was handed to the channel (22-23 fix): the place the remote action log records that refusal as one DENIED entry.The UltiCloud protocol v2 layer of one agent connection attempt (as of 6.3.1): the versioned handshake, the per-connection limits, the reliable-event resend and acknowledgement, the overflow report, inbound control errors and the liveCloudChannel.Lifecycle callbacks of one connection; never invoked while this protocol's lock is held.One validated welcome.The operator settings the panel mirrors next to its remote controls: thesettingsobject of the openinghello, and asettings.changedpayload only when the value differs from the last one reported.One attempt's Java-WebSocket client for the UltiCloud/v1/agentsocket (as of 6.3.1).Utility class for annotation processing operations.Simple rate limiter for UltiCloud API calls.Basic type determination utility class.Bean copy utility class.Turns the handler's stop or restart into one main-thread scheduler task, and answers whether a restart would actually restart this server.The module catalogue of protocol v2, read over/v1/catalogue/*(plans 22-18 and 22-26, D-27, D-28).One version of one module, as the catalogue describes it.The HTTP the module catalogue is asked with (plan 22-18, S-27, S-61).A finished download.A JSON answer.What happened to one request.Utility class for ensuring proper class loader usage throughout the plugin.GEN-07's observe-only classload filter audit (D-14): reproduces the exact matching semantics of the three name-based filter layersSecurityPolicy.isSafeClassName(String)used to enforce before D-12/D-13, and records what each removed layer WOULD have refused -- it refuses nothing itself.The four removed filter layers, in the exact orderisSafeClassNameevaluated them.The three command-facing entry points behind/ulticloud login|logout|status.An immutable view ofCloudAuthManager.status()'s result.The outcomes ofCloudAuthManager.login(DeviceLoginListener).Completed unlink outcomes; none contains a credential.Immutable result of a manual reconnect request; an accepted attempt runs asynchronously.Whether a retry was accepted, or the reason no retry was queued.The inbound UltiCloud features of one enabled plugin (plan 22-21, D-26, S-59, S-60); internal, not for module use.The ports the inbound handlers are built from.The single JSON REST exchange the protocol v2 client uses against UltiCloud (/v1/*).What happened to one request.The result of one exchange.The bounded buffer of reliable events not yet acknowledged by the UltiCloud gateway (D-11, D-14, D-15).One unacknowledged reliable event.The persisted view of the buffer, read atomically byCloudOutbox.snapshot().Captures player joins and leaves into the current UltiCloud session's reliable-delivery outbox (D-14, D-17, S-16), whether or not the connection is open: the outbox exists precisely to carry an event across a disconnect (contract answer 15).The single owner of one UltiCloud login's entire lifetime.The mutable state of one device-code poll; touched only by its poll steps, one at a time.Schedules one device-login step; the test seam ofCloudSession.setDeviceSeamsForTesting(com.ultikits.ultitools.utils.DeviceAuthorizationClient, com.ultikits.ultitools.utils.CloudSession.DeviceStepScheduler, java.util.function.LongSupplier).Persists the reliable-delivery state -- theCloudOutboxand theCommandDedupeSet-- in<server root>/.ultikits/cloud-outbox.json(D-15, D-17, S-15), so unacknowledged events and recently seen command ids survive a restart.The validated content of a state file.A state file that cannot be used as a whole; the message names the reason, never the content.Turns a module'sCodeSource.getLocation()URL into theFileit names -- the one resolver the language subsystem uses, so language discovery (Localized.supported()), the dictionary reader and resource extraction inUltiToolsPlugincan never disagree about where a module's JAR (or exploded class directory) is (#676 case 26).The ids of commands the UltiCloud gateway delivered recently, so a redelivered command is acknowledged but not run twice (D-16, D-17).One remembered command id, when it was first seen and its receipt, if any.Common utility class providing general-purpose helper methods.Utility class for configuration editor operations.Frozen protocol patterns shared by framework validators; internal, not for module use.Persists a rotated server credential and only then acknowledges it.Writes a rotated credential durably.The single owner ofdata.json. Any other class that opens a reader or writer on that file is a defect (D-12) -- route the operation throughCredentialStore.read(),CredentialStore.write(Map)orCredentialStore.update(UnaryOperator)instead.The outcome of aCredentialStore.read()call.Shared command-id and player-link receipt ledger; internal, not for module use.Utility class for handling plugin dependency and package scanning operations.The two REST calls of the RFC 8628 device authorization grant against UltiCloud protocol v2:POST /v1/device/authorizeandPOST /v1/device/token.Either aDeviceAuthorizationClient.Grantor the operator-facing reason the request failed.A device code and how to present it.The outcome of one token poll.RFC 8628 §3.5 outcomes, plus the two local ones.Utility class for economy operations using Vault.One frame's match outcome: theEconomyUtils.MatchKind, plus the resolved module name when (and only when)kind == RESOLVED.The three possible outcomes of matching one stack frame againstprefixToModule(Codex P2, PR #463, round 3): a barenullreturn collapsed "this frame belongs to no registered module" and "this frame's closest root is claimed by two or more DIFFERENT modules" into the same value, and the last two review rounds both found a defect that traces straight back to that conflation — aNONEframe must let the per-frame walk continue outward (a real non-match, no evidence either way), while anAMBIGUOUSframe must terminate the walk immediately (real evidence that a module frame exists here, but WHICH module cannot be determined) — seeEconomyUtils.attributeModule(StackTraceElement[], Map)'s own javadoc for why continuing past an ambiguous frame is itself the bug.File operation utility class.Frames protocol replies over a socket handoff, enforcing correlation and UTF-8 frame limits.Resolves the framework's own operator-, player-, panel- and e-mail-facing text through the language catalogue (lang/en.json,lang/zh.json), so it follows the server'slanguagesetting.Utility class for HTTP file download operations.Progress callback interface for download operations.The UltiCloud base URL, plus the three protected protocol v1 REST calls kept so 6.3.0 subclasses still link.A fluent builder for creating ItemStacks with various properties.Utility class for ItemStack serialization and deserialization.JSON path utility class - replaces hutool-json's putByPath/getByPath functionalityNormalises this server's stored install id (uuidincredentials.json) into thelegacyServerUuidvalue of the device authorization request (attachToServerIdis the panel's field on/v1/device/approve, never sent by the plugin).Message utils.An extremely simple JSON builder.A super simple representation of a JSON object.Themodules:<id>@<X.Y.Z>capability names an UltiCloud protocol v2hellodeclares for the modules that answermodule.request; internal, not for module use.The files of the module subsystem and the transactions that change them: which folder modules load from, and how/upm updatereplaces a module's JAR (#505, #513).Where the latest version of a module, and its download, come from.Named points of a transaction; a test crashes at one to reproduce that window.How a JAR is downloaded.A file a destructive step touches, and the recorded hashes it may hold; none means it must be absent.How files are moved and deleted; a test substitutes a failing one.File work that may fail with anIOException.The catalogue keys of every line this class produces.A step found a file the transaction cannot identify; the record is held for the operator.Thrown byModuleFileTransactions.Catalogue.latestVersion(java.lang.String)when the catalogue answers that versions of the module exist but none is compatible with this framework's API level (HTTP 409 from the level-filteredlatest; plan 18-40), so staging can say so instead of "no download".The persisted record of one transaction.WhatModuleFileTransactions.recordedIdentity(com.ultikits.ultitools.utils.ModuleFileTransactions.Removal, java.io.File)found: the same file, a different file, or -- with the read error -- a file whose content could not be read to tell.A record whose names would leave their folder, or that this version does not understand.One file aREMOVErecord deletes at the next start, and what it was when recorded.A module an uninstall removed, in every form a transaction can name it by: the identify-strings and runtime names of the instances it unloaded (plus the argument it was given), and the file names of its JARs -- the ones those instances were loaded from, the ones the start-up scan recorded as declaring their main class, and the ones it deleted or recorded for deletion.One line for the start-up log, with its catalogue key and arguments.WhatModuleFileTransactions.reserve(com.ultikits.ultitools.utils.ModuleFileTransactions.Record, java.io.File, java.lang.String, java.util.List<com.ultikits.ultitools.abstracts.UltiToolsPlugin>, java.util.function.Function<com.ultikits.ultitools.abstracts.UltiToolsPlugin, java.io.File>)decided: the module and JAR to stage an update for, or the refusal.Which start-up step a rollback is finished from; it decides what the log line says.The outcome.The one derivation of a module's UltiCloud identifier; internal, not for module use.Bridges UltiCloud protocol v2module.requestto the released 6.3.0PanelResponderRegistry; internal, not for module use.Turns a silently-skipped class from a module's startup scan into a single, named, loud line an operator actually reads (D-19).What the framework and its modules share about official language files (#608).Logs why a framework language file was not replaced; the file stays as it was in every case but one.The single atomic, owner-only file writer behind both framework-owned files under<server root>/.ultikits/:CredentialStore'scredentials.jsonandCloudStateStore'scloud-outbox.json.Writes the complete content of the file toout; the writer is flushed and closed by the caller.Utility class for package scanning and class discovery operations.Strict protocol payload reader shared by framework handlers; internal, not for module use.Handles the structuredplayer.actionrequest — kick, game mode and teleport — as Bukkit API calls on the main thread.One validated request, independent of the payload object it was read from.The audit port integration binds to the remote action log; one entry per executed or refused action, none for a payload that never ran.One validated teleport target: another online player, or a world and a position.Carries the player-link protocol behindCloudPlayerLinks: it framesplayer.link.create, correlates the answer by envelope id, delivers completions and expiries to the single owning module, and records each completion result in the shared ledger before answering the gateway.A completion that arrived before its create was answered.The owning module and its handler.One create this run issued and has not answered yet.The player fields shared by completions and expiries.Start-up and shutdown entry points of the UltiCloud connection.Utility class for plugin installation and management operations.Raised when the name the operator typed could be more than one loaded module's, so the uninstall changed nothing.What one archive says about which module it holds -- the single reader both identity resolution and entry classification use, so the two cannot drift apart.What one entry of the modules folder is, relative to the module being uninstalled.The reasons, as catalogue keys (Chinese, with their English values inlang/en.json); a nestedKeysholder likeModuleFileTransactions.Keys.Everything later decisions need about which module this is, resolved once.Raised when a module's own unload threw.What a filesystem probe answered, keeping "unknown" out of "no".What the module loader and the loaded instances say about an uninstall's targets, read before anything is unloaded.The uninstall could not delete these JARs now -- the running server holds them open, or the folder is not writable -- and has recorded them, so the next start deletes them before any module loads (#518).The uninstall could not delete these JARs now and could not record their deletion for the next start either (#518).The catalogue and downloader of one staging call (plan 22-26 fix round).The entries an uninstall could not identify, carried on whatever failure leaves the method.Raised when the uninstall refuses to act because its outcome would be undefined: two possible targets, or a target whose JAR another running module shares.What an uninstall did, and what it could not determine.Forwards the records of a dedicated diagnostics logger to the framework's own plugin logger, so they reach the server console at their real level and in the server's normal log format (#557).Reads a module's ownplugin.ymlstraight from its class's code source, given only a bareClass<?>- before anyUltiToolsPlugininstance exists (D-12).The subset of a module'splugin.ymlthis framework needs: its declaredname:andmain:(both nullable - absent when the archive has none or reading failed), itsloadAfter:list, and its Bukkit-levelsoftdepend:/depend:lists (all three never null; empty when absent or reading failed), and its declaredversion:andapi-version:as text (both nullable, like name and main), which the load-failure refusal quotes to identify the module.Shared implementation of the "replace a file in place, preserving what the operator set up" operation used by everycreateTempFile+ atomic-Files.move(java.nio.file.Path, java.nio.file.Path, java.nio.file.CopyOption...)replace-in-place site in this framework.Callbacks aPosixAttributePreserver.replaceInPlace(java.io.File, byte[], com.ultikits.ultitools.utils.PosixAttributePreserver.ReplaceInPlaceListener)caller supplies so each replace-in-place site can log accurate, resource-specific wording for exactly how the operation was declined or degraded -- this shared operation does not know or care whethertargetis a language catalogue or a provenance sidecar, only the caller does.Handles the ack-firstserver.powerrequest: a structured stop or restart that never passes through the command blocklist and is allowed only while the operator'sultipanel.capabilities.power-actionsswitch is on.The two callsBukkitPowerExecutorturns into a main-thread stop or restart, kept behind an interface so the handler stays unit-testable without a live server.Reconnect delays for the UltiCloud agent connection, with full jitter (as of 6.3.1).Reflection utility class.Handles a validatedcommand.executethrough the shared acknowledgement and dedupe gate.An output array plus whether the byte cap forced lines to be dropped.The typed entry model of one module configuration file, and the per-key check of a panel change.One editable setting: its dotted key, label, type, comment line, value and constraints.The declared Java types the contract can carry.The three structured-configuration requests of protocol v2: browse the registered configuration files, read one file's typed entries with the version of its bytes, and write exactly the keys the panel names - only while the file still holds the bytes the panel read.One change accepted for the write, with the entry that types it.One panel change, already shape-checked.One row ofconfig.update.result's per-key array.Records the SHA-256 digest of every resource fileUltiToolsPlugin.saveResources(boolean)extracts, so a later boot can distinguish "the operator edited this file" from "an old jar extracted this and nobody has touched it since" (#441, D-05/D-06/D-07).Provides NO runtime constraint on class loading or reflection (GEN-07, D-12, since 6.3.0).SecurityPolicy.isSafeClassName(String)andSecurityPolicy.isSafeParameterType(Class)now unconditionally returntrue;SecurityPolicy.addTrustedPackage(String)andSecurityPolicy.addDangerousClass(String)are no-ops.One dedicated worker thread for the file andserver.propertiesrequests of one connection (plan 22-21 fix round).The per-server UltiCloud credential (protocol v2, prefixucs_) and the facts the device authorization returned with it.The only reader and writer of thecloud_credentialentry of<server root>/.ultikits/credentials.json, always throughCredentialStore.TheDedupeLedgerevery inbound handler of the framework shares (plan 22-21, D-17 as narrowed by S-52, S-59): the command-id set and the receipts live in the current session'sCommandDedupeSet, andSessionDedupeLedger.persistNow()writes them, with the outbox, tocloud-outbox.jsonthrough the session'sCloudStateStore.The state of one session: its id set, its state file and the server id the file is written for.The shutdown window of the inbound UltiCloud requests that change server state (22-23 shutdown-window round, maintainer decision of 2026-10-26); internal, not for module use.How a refused type is answered.The one shutdown signal; see the class comment.Deprecated, for removal: This API element is subject to removal in a future version.Deprecated, for removal: This API element is subject to removal in a future version.There is no replacement, as forSimpleHttpClient.ADraft_6455that records the HTTP status of the upgrade response, so the agent socket can tell a refused upgrade (401, 402, 426, 429, ...) from a lost connection (as of 6.3.1).ULID generation and validation for UltiCloud protocol v2 envelope ids (D-11, D-21): 26 Crockford base32 characters (0123456789ABCDEFGHJKMNPQRSTVWXYZ), a 48-bit millisecond timestamp followed by 80 random bits, as in the ULID specification (https://github.com/ulid/spec).Deprecated, for removal: This API element is subject to removal in a future version.UseCloudPlayerLinksto link a player; protocol 2.0.0 has no v1 REST cloud, so every call of this class is refused.Deprecated, for removal: This API element is subject to removal in a future version.There is no replacement:CloudPlayerLinksreports its own outcomes.Deprecated, for removal: This API element is subject to removal in a future version.There is no replacement:CloudPlayerLinksreports its own outcomes.What the gateway said when it refused the agent socket's upgrade request (as of 6.3.1).Downloads a module JAR and verifies it before anything may use it (plan 22-18, D-28, S-23).Why a download was or was not accepted.What one verified download did.Semantic version comparison utility class.The answer to one catalogue version lookup, as the start-up update check needs it: a version was found, the catalogue confirmed it has nothing to offer, or the lookup failed (the catalogue could not be reached, answered with an error status, or sent a body that could not be read).What the lookup established.Utility class for version checking and comparison operations.Cross-version compatibility utility class using XSeries.
HttpURLConnectionor an HTTP client library of your own; the framework no longer needs a general HTTP helper.