Skip to content

Configuration

Jump to bottom
Jeremy Fail edited this page Nov 7, 2026 · 1 revision

The PluginUpdateChecker offers various options to configure behavior of update checks. Configure a PluginUpdateChecker instance after construction and before (or between) checkNow / scheduleRepeating calls. Almost every setter returns this for chaining.

Suggested order: construct → configure links / notifications / HTTP → set callbacks → start checks.

PluginUpdateChecker checker = new PluginUpdateChecker(this, "Owner/Repo");

checker.setDownloadUrl("https://example.com/releases")
    .setSupportUrl("https://example.com/support")
    .setConnectTimeoutMs(10_000)
    .setNotifyOperatorsOnJoin(true)
    .setOnFailure(ex -> getLogger().warning("Update check failed: " + ex.getMessage()));

checker.checkNow();
checker.scheduleRepeating(6, TimeUnit.HOURS);

For constructors and how “latest” is resolved, see Version sources and comparison.
For checkNow / scheduling behavior, see Running checks, scheduler, HTTP.
For events and built-in message text, see Events, callbacks, notifications.

Version and GitHub source

Method Default Notes
setInstalledVersion(String) plugin.yml version Override the local version used for comparison (trimmed). null restores plugin.yml.
setIncludeGitHubPrereleases(boolean) false GitHub constructor only. false → GET .../releases/latest (stable). true → GET .../releases and use the newest created release (may be a pre-release). Read with isIncludeGitHubPrereleases(). Ignored for plain-text URL and custom RemoteVersionSupplier constructors.
setUsingPaidVersion(boolean) false Affects which download URL(s) are preferred (getAppropriateDownloadLinks()) and adds ; paid to the default User-Agent. Read with isUsingPaidVersion().

HTTP and User-Agent

Method Default Notes
setConnectTimeoutMs(int) 0 Connect timeout for built-in HTTP (HttpURLConnection). 0 = do not set (JVM default). Must be >= 0. Read timeout is never set by this library.
setUserAgent(String) composed default Full User-Agent override. null or empty clears the override so the default builder path is used again.
setUserAgentResourceUserId(String) unset When using the default UA, appends uid/.... null clears. Reserved for marketplace-style ids.
getDefaultUserAgentBuilder() empty extras Append extra segments to the default UA (appendRaw, appendPlugin, etc.). Ignored while a full setUserAgent override is active.

Default User-Agent shape (when not overridden):

PluginUpdateChecker/<libVersion> (<plugin>/<version>; Minecraft/...; Bukkit/...; optional paid; optional uid/...; extras)

Download and related links

See the Download Links, Getters, Relocation, Chat, Types page for more.

Blank or null URL arguments clear that setting (blankToNull).

Method Default Notes
setDownloadUrl(String) unset Single download URL when free/paid URLs are not used.
setDownloadUrls(String freeUrl, String paidUrl) unset Separate free and paid download URLs.
setDownloadLinkLabels(String freeLabel, String paidLabel) "Free" / "Paid" Labels for chat/console when both free and paid URLs are set. Empty/null arguments leave the existing label unchanged.
setChangelogUrl(String) unset Player chat “Changelog” link only (not printed in the console update box). Getter: getChangelogLink().
setDonationUrl(String) unset Player chat and console update box. Getter: getDonationLink().
setSupportUrl(String) unset Player chat and console update box. Getter: getSupportLink().

Which download links are shown?

getAppropriateDownloadLinks() decides the list used by built-in notifications:

  1. If both free and paid URLs are set → returns those two (order depends on setUsingPaidVersion: paid-first when paid, free-first when free).
  2. Else if a single setDownloadUrl is set → that one URL.
  3. Else → whichever of free/paid is set alone, if any.
  4. Else → empty list (no download lines).

Built-in notifications

See the Events, callbacks, notifications page for more.

These control the library’s own console/player messaging. They do not disable PluginUpdateCheckEvent or your setOnSuccess / setOnFailure callbacks.

Method Default Notes
setNotifyRequestorsOnCheck(boolean) true After a check, send built-in messages to the check’s requestors (players / console). false = events/callbacks only for that path. Silent checks (checkNow with empty/null requestors, or scheduled repeats) never use requestor messaging.
setNotifyRequestorsWhenUpToDate(boolean) true When requestors triggered the check and the result is up to date, allow the “running the latest version” player chat line. Join notices never show that line.
setSuppressUpToDateConsoleMessage(boolean) false When true, hide the console “latest version” info line after an up-to-date check (requestor flow).
setColoredConsoleOutput(boolean) false Prefix some console update-box lines with legacy ChatColor codes.
setNotifyOperatorsOnJoin(boolean) true Operators may receive join-time notices after at least one check has completed.
setNotifyPermissionOnJoin(String) unset Extra permission for join-time notices. null/blank disables the permission path. Getter: getNotifyPermission().

Join notices (after at least one completed check):

  • Update available → update-style message
  • Up to date → no message
  • Failure / unknown → short “could not check” style line

Eligible if setNotifyOperatorsOnJoin(true) and the player is op, or they have setNotifyPermissionOnJoin(...).

Callbacks

See the Events, callbacks, notifications page for more.

Method Default Notes
setOnSuccess(UpdateSuccessCallback) none Main thread after a successful fetch (before the event on the same sync hop). null clears. Receives requestors + latest version string.
setOnFailure(Consumer<Throwable>) short warning Main thread after the supplier throws. Default: one plugin-logger warning with the error detail (no stack dump). Pass null for a silent no-op.

Failures are always caught by the library (network errors, bad JSON, etc.). You choose how loud the callback is; you do not need to wrap checkNow in try/catch for HTTP failures.

Clone this wiki locally