Implementation:Apache Paimon RESTToken

Knowledge Sources	Apache_Paimon
Domains	Authentication, Security, Token Management
Last Updated	2026-02-08 00:00 GMT

Overview

RESTToken represents a token credential for REST Catalog file I/O access with expiration tracking and efficient hash code caching.

Description

RESTToken is a serializable token holder class that encapsulates authentication credentials used by the REST Catalog to access file I/O operations. The token is stored as a map of string key-value pairs, allowing flexibility in the token format and supporting different authentication mechanisms that may require multiple credential components.

The class includes an expiration timestamp (in milliseconds) to enable token refresh logic and prevent using expired credentials. This is essential for implementing automatic token renewal in long-running applications that maintain persistent connections to the REST catalog.

A notable performance optimization in this class is the caching of the hash code value. Since tokens are immutable once created and may be used frequently in hash-based collections (like HashMap or HashSet), computing the hash code once and storing it provides better performance. The hash code is computed lazily on the first call to hashCode() and then reused for all subsequent calls.

Usage

Use RESTToken when working with REST Catalog authentication that requires token-based credentials for accessing file I/O operations. It's typically used internally by the catalog implementation to store and manage authentication tokens with expiration handling.

Code Reference

Source Location

Repository: Apache_Paimon
File: paimon-api/src/main/java/org/apache/paimon/rest/RESTToken.java

Signature

public class RESTToken implements Serializable {
    private static final long serialVersionUID = 1L;

    private final Map<String, String> token;
    private final long expireAtMillis;

    @Nullable
    private Integer hash;

    public RESTToken(Map<String, String> token, long expireAtMillis);

    public Map<String, String> token();

    public long expireAtMillis();

    @Override
    public boolean equals(Object o);

    @Override
    public int hashCode();
}

Import

import org.apache.paimon.rest.RESTToken;

I/O Contract

Inputs

Name	Type	Required	Description
token	Map<String, String>	Yes	Token credentials as key-value pairs
expireAtMillis	long	Yes	Expiration timestamp in milliseconds since epoch

Outputs

Name	Type	Description
token()	Map<String, String>	Returns the token credential map
expireAtMillis()	long	Returns the expiration timestamp in milliseconds
equals()	boolean	Compares tokens for equality based on content and expiration
hashCode()	int	Returns cached hash code for efficient collection operations

Usage Examples

import org.apache.paimon.rest.RESTToken;
import java.util.HashMap;
import java.util.Map;

// Example 1: Create a simple bearer token
Map<String, String> bearerToken = new HashMap<>();
bearerToken.put("Authorization", "Bearer eyJhbGciOiJIUzI1NiIs...");

// Token expires in 1 hour
long expirationTime = System.currentTimeMillis() + (60 * 60 * 1000);
RESTToken token = new RESTToken(bearerToken, expirationTime);

// Example 2: Create a multi-credential token (e.g., for cloud storage)
Map<String, String> cloudCredentials = new HashMap<>();
cloudCredentials.put("access-key-id", "AKIAIOSFODNN7EXAMPLE");
cloudCredentials.put("secret-access-key", "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY");
cloudCredentials.put("session-token", "FwoGZXIvYXdzEBQaD...");

// Token expires in 12 hours
long expiration = System.currentTimeMillis() + (12 * 60 * 60 * 1000);
RESTToken cloudToken = new RESTToken(cloudCredentials, expiration);

// Example 3: Check if token is expired
public boolean isTokenExpired(RESTToken token) {
    return System.currentTimeMillis() >= token.expireAtMillis();
}

// Example 4: Use token in file I/O operations
public void accessFile(RESTToken token, String filePath) {
    if (isTokenExpired(token)) {
        throw new IllegalStateException("Token has expired");
    }

    Map<String, String> credentials = token.token();
    // Use credentials to access file...
}

// Example 5: Token refresh logic
public RESTToken refreshIfNeeded(RESTToken currentToken,
                                  TokenRefreshFunction refresher) {
    // Refresh 5 minutes before expiration
    long refreshThreshold = 5 * 60 * 1000;
    long timeUntilExpiry = currentToken.expireAtMillis() - System.currentTimeMillis();

    if (timeUntilExpiry < refreshThreshold) {
        return refresher.refresh();
    }

    return currentToken;
}

// Example 6: Using tokens in collections
Set<RESTToken> tokenCache = new HashSet<>();
tokenCache.add(token);

// Efficient lookup thanks to cached hash code
if (tokenCache.contains(token)) {
    System.out.println("Token found in cache");
}

// Example 7: Token comparison
RESTToken token1 = new RESTToken(bearerToken, expirationTime);
RESTToken token2 = new RESTToken(bearerToken, expirationTime);

if (token1.equals(token2)) {
    System.out.println("Tokens are identical");
}

// Example 8: Extract specific credentials
Map<String, String> creds = cloudToken.token();
String accessKey = creds.get("access-key-id");
String secretKey = creds.get("secret-access-key");
System.out.println("Using access key: " + accessKey);

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment