/* * Copyright 2026 macuguita * * Licensed under the EUPL, Version 1.2 or – as soon they will be approved by * the European Commission - subsequent versions of the EUPL (the "Licence"); * You may not use this work except in compliance with the Licence. * You may obtain a copy of the Licence at: * * https://joinup.ec.europa.eu/software/page/eupl * * Unless required by applicable law or agreed to in writing, software * distributed under the Licence is distributed on an "AS IS" basis, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the Licence for the specific language governing permissions and * limitations under the Licence. */ package com.macuguita.lib.api.persista; import java.util.Optional; import java.util.UUID; import java.util.concurrent.CompletableFuture; /** * A handle to a piece of persistent player data stored in Persista. * Instances are created via {@link PersistaAPI#register}. * *
This method may perform an HTTP request if no valid cached value exists.
* *This operation is asynchronous and may be subject to server rate limiting (HTTP 429).
*/ CompletableFutureIf the cached value is stale or missing, this method may trigger * an asynchronous background fetch.
* *Repeated calls may therefore indirectly result in network traffic.
*/ OptionalThis method may still trigger background refresh behavior depending on cache state.
*/ T getOrDefault(UUID playerId, T defaultValue); /** * Returns cached data without triggering any network activity. * *This method is fully local and safe to call in performance-critical loops.
*/ OptionalThis operation performs asynchronous network communication and may be * rejected by the server with HTTP 429 (rate limited).
* *Callers MUST avoid spamming updates. The library does not throttle writes.
* * @throws UnsupportedOperationException if called on the server side */ CompletableFuture