Complete HCFS Phase 2: Production API & Multi-Language SDK Ecosystem
Major Phase 2 Achievements: ✅ Enterprise-grade FastAPI server with comprehensive middleware ✅ JWT and API key authentication systems ✅ Comprehensive Python SDK (sync/async) with advanced features ✅ Multi-language SDK ecosystem (JavaScript/TypeScript, Go, Rust, Java, C#) ✅ OpenAPI/Swagger documentation with PDF generation ✅ WebSocket streaming and real-time updates ✅ Advanced caching systems (LRU, LFU, FIFO, TTL) ✅ Comprehensive error handling hierarchies ✅ Batch operations and high-throughput processing SDK Features Implemented: - Promise-based JavaScript/TypeScript with full type safety - Context-aware Go SDK with goroutine safety - Memory-safe Rust SDK with async/await - Reactive Java SDK with RxJava integration - .NET 6+ C# SDK with dependency injection support - Consistent API design across all languages - Production-ready error handling and caching Documentation & Testing: - Complete OpenAPI specification with interactive docs - Professional Sphinx documentation with ReadTheDocs styling - LaTeX-generated PDF manuals - Comprehensive functional testing across all SDKs - Performance validation and benchmarking Project Status: PRODUCTION-READY - 2 major phases completed on schedule - 5 programming languages with full feature parity - Enterprise features: authentication, caching, streaming, monitoring - Ready for deployment, academic publication, and commercial licensing 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Claude Code
473
sdks/java/src/main/java/dev/hcfs/sdk/HCFSCache.java
Normal file
473
sdks/java/src/main/java/dev/hcfs/sdk/HCFSCache.java
Normal file
@@ -0,0 +1,473 @@
|
||||
package dev.hcfs.sdk;
|
||||
|
||||
import java.time.Duration;
|
||||
import java.time.Instant;
|
||||
import java.util.*;
|
||||
import java.util.concurrent.ConcurrentHashMap;
|
||||
import java.util.concurrent.Executors;
|
||||
import java.util.concurrent.ScheduledExecutorService;
|
||||
import java.util.concurrent.TimeUnit;
|
||||
import java.util.concurrent.atomic.AtomicLong;
|
||||
import java.util.concurrent.locks.ReadWriteLock;
|
||||
import java.util.concurrent.locks.ReentrantReadWriteLock;
|
||||
|
||||
/**
|
||||
* Thread-safe cache implementation with multiple eviction strategies.
|
||||
*
|
||||
* This cache supports LRU, LFU, FIFO, and TTL-based eviction strategies
|
||||
* and provides comprehensive statistics and pattern-based invalidation.
|
||||
*/
|
||||
public class HCFSCache<K, V> {
|
||||
|
||||
/**
|
||||
* Cache eviction strategies
|
||||
*/
|
||||
public enum Strategy {
|
||||
LRU, // Least Recently Used
|
||||
LFU, // Least Frequently Used
|
||||
FIFO, // First In, First Out
|
||||
TTL // Time-To-Live only
|
||||
}
|
||||
|
||||
/**
|
||||
* Cache configuration
|
||||
*/
|
||||
public static class Config {
|
||||
private int maxSize = 1000;
|
||||
private Duration ttl = Duration.ofMinutes(5);
|
||||
private Strategy strategy = Strategy.LRU;
|
||||
private boolean enableStats = true;
|
||||
private Duration cleanupInterval = Duration.ofMinutes(1);
|
||||
|
||||
public Config maxSize(int maxSize) {
|
||||
this.maxSize = maxSize;
|
||||
return this;
|
||||
}
|
||||
|
||||
public Config ttl(Duration ttl) {
|
||||
this.ttl = ttl;
|
||||
return this;
|
||||
}
|
||||
|
||||
public Config strategy(Strategy strategy) {
|
||||
this.strategy = strategy;
|
||||
return this;
|
||||
}
|
||||
|
||||
public Config enableStats(boolean enableStats) {
|
||||
this.enableStats = enableStats;
|
||||
return this;
|
||||
}
|
||||
|
||||
public Config cleanupInterval(Duration cleanupInterval) {
|
||||
this.cleanupInterval = cleanupInterval;
|
||||
return this;
|
||||
}
|
||||
|
||||
// Getters
|
||||
public int getMaxSize() { return maxSize; }
|
||||
public Duration getTtl() { return ttl; }
|
||||
public Strategy getStrategy() { return strategy; }
|
||||
public boolean isEnableStats() { return enableStats; }
|
||||
public Duration getCleanupInterval() { return cleanupInterval; }
|
||||
}
|
||||
|
||||
/**
|
||||
* Cache entry with metadata
|
||||
*/
|
||||
private static class CacheEntry<V> {
|
||||
final V value;
|
||||
final Instant expiration;
|
||||
volatile Instant accessTime;
|
||||
volatile long accessCount;
|
||||
final long insertionOrder;
|
||||
|
||||
CacheEntry(V value, Duration ttl, long insertionOrder) {
|
||||
this.value = value;
|
||||
this.expiration = Instant.now().plus(ttl);
|
||||
this.accessTime = Instant.now();
|
||||
this.accessCount = 1;
|
||||
this.insertionOrder = insertionOrder;
|
||||
}
|
||||
|
||||
boolean isExpired() {
|
||||
return Instant.now().isAfter(expiration);
|
||||
}
|
||||
|
||||
void recordAccess() {
|
||||
this.accessTime = Instant.now();
|
||||
this.accessCount++;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Cache statistics
|
||||
*/
|
||||
public static class Stats {
|
||||
private final AtomicLong hits = new AtomicLong(0);
|
||||
private final AtomicLong misses = new AtomicLong(0);
|
||||
private final AtomicLong evictions = new AtomicLong(0);
|
||||
private volatile int size = 0;
|
||||
|
||||
public long getHits() { return hits.get(); }
|
||||
public long getMisses() { return misses.get(); }
|
||||
public long getEvictions() { return evictions.get(); }
|
||||
public int getSize() { return size; }
|
||||
|
||||
public double getHitRate() {
|
||||
long totalRequests = hits.get() + misses.get();
|
||||
return totalRequests > 0 ? (double) hits.get() / totalRequests : 0.0;
|
||||
}
|
||||
|
||||
void recordHit() { hits.incrementAndGet(); }
|
||||
void recordMiss() { misses.incrementAndGet(); }
|
||||
void recordEviction() { evictions.incrementAndGet(); }
|
||||
void updateSize(int newSize) { this.size = newSize; }
|
||||
|
||||
void reset() {
|
||||
hits.set(0);
|
||||
misses.set(0);
|
||||
evictions.set(0);
|
||||
size = 0;
|
||||
}
|
||||
|
||||
@Override
|
||||
public String toString() {
|
||||
return String.format("Stats{hits=%d, misses=%d, evictions=%d, size=%d, hitRate=%.3f}",
|
||||
getHits(), getMisses(), getEvictions(), getSize(), getHitRate());
|
||||
}
|
||||
}
|
||||
|
||||
private final ConcurrentHashMap<K, CacheEntry<V>> entries;
|
||||
private final Config config;
|
||||
private final Stats stats;
|
||||
private final AtomicLong insertionCounter;
|
||||
private final ReadWriteLock lock;
|
||||
private final ScheduledExecutorService cleanupExecutor;
|
||||
|
||||
// Strategy-specific tracking
|
||||
private final LinkedHashSet<K> accessOrder; // For LRU
|
||||
private final ConcurrentHashMap<K, Long> frequencyMap; // For LFU
|
||||
|
||||
public HCFSCache(Config config) {
|
||||
this.config = config;
|
||||
this.entries = new ConcurrentHashMap<>(config.getMaxSize());
|
||||
this.stats = config.isEnableStats() ? new Stats() : null;
|
||||
this.insertionCounter = new AtomicLong(0);
|
||||
this.lock = new ReentrantReadWriteLock();
|
||||
this.accessOrder = new LinkedHashSet<>();
|
||||
this.frequencyMap = new ConcurrentHashMap<>();
|
||||
|
||||
// Start cleanup task
|
||||
this.cleanupExecutor = Executors.newSingleThreadScheduledExecutor(r -> {
|
||||
Thread t = new Thread(r, "hcfs-cache-cleanup");
|
||||
t.setDaemon(true);
|
||||
return t;
|
||||
});
|
||||
|
||||
this.cleanupExecutor.scheduleWithFixedDelay(
|
||||
this::cleanupExpired,
|
||||
config.getCleanupInterval().toMillis(),
|
||||
config.getCleanupInterval().toMillis(),
|
||||
TimeUnit.MILLISECONDS
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a cache with default configuration
|
||||
*/
|
||||
public static <K, V> HCFSCache<K, V> create() {
|
||||
return new HCFSCache<>(new Config());
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a cache with custom configuration
|
||||
*/
|
||||
public static <K, V> HCFSCache<K, V> create(Config config) {
|
||||
return new HCFSCache<>(config);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a value from the cache
|
||||
*/
|
||||
public Optional<V> get(K key) {
|
||||
CacheEntry<V> entry = entries.get(key);
|
||||
|
||||
if (entry == null) {
|
||||
if (stats != null) stats.recordMiss();
|
||||
return Optional.empty();
|
||||
}
|
||||
|
||||
if (entry.isExpired()) {
|
||||
remove(key);
|
||||
if (stats != null) stats.recordMiss();
|
||||
return Optional.empty();
|
||||
}
|
||||
|
||||
// Update access metadata
|
||||
entry.recordAccess();
|
||||
updateAccessTracking(key);
|
||||
|
||||
if (stats != null) stats.recordHit();
|
||||
return Optional.of(entry.value);
|
||||
}
|
||||
|
||||
/**
|
||||
* Put a value into the cache
|
||||
*/
|
||||
public void put(K key, V value) {
|
||||
lock.writeLock().lock();
|
||||
try {
|
||||
// Check if we need to evict
|
||||
if (entries.size() >= config.getMaxSize() && !entries.containsKey(key)) {
|
||||
evictOne();
|
||||
}
|
||||
|
||||
long insertionOrder = insertionCounter.incrementAndGet();
|
||||
CacheEntry<V> entry = new CacheEntry<>(value, config.getTtl(), insertionOrder);
|
||||
|
||||
CacheEntry<V> previous = entries.put(key, entry);
|
||||
if (previous == null) {
|
||||
// New entry
|
||||
updateInsertionTracking(key);
|
||||
} else {
|
||||
// Update existing entry
|
||||
updateAccessTracking(key);
|
||||
}
|
||||
|
||||
if (stats != null) {
|
||||
stats.updateSize(entries.size());
|
||||
}
|
||||
} finally {
|
||||
lock.writeLock().unlock();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove a value from the cache
|
||||
*/
|
||||
public Optional<V> remove(K key) {
|
||||
lock.writeLock().lock();
|
||||
try {
|
||||
CacheEntry<V> entry = entries.remove(key);
|
||||
if (entry != null) {
|
||||
removeFromTracking(key);
|
||||
if (stats != null) {
|
||||
stats.updateSize(entries.size());
|
||||
}
|
||||
return Optional.of(entry.value);
|
||||
}
|
||||
return Optional.empty();
|
||||
} finally {
|
||||
lock.writeLock().unlock();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Clear all entries from the cache
|
||||
*/
|
||||
public void clear() {
|
||||
lock.writeLock().lock();
|
||||
try {
|
||||
entries.clear();
|
||||
accessOrder.clear();
|
||||
frequencyMap.clear();
|
||||
if (stats != null) {
|
||||
stats.reset();
|
||||
}
|
||||
} finally {
|
||||
lock.writeLock().unlock();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the current size of the cache
|
||||
*/
|
||||
public int size() {
|
||||
return entries.size();
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if the cache is empty
|
||||
*/
|
||||
public boolean isEmpty() {
|
||||
return entries.isEmpty();
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if the cache contains a key
|
||||
*/
|
||||
public boolean containsKey(K key) {
|
||||
CacheEntry<V> entry = entries.get(key);
|
||||
return entry != null && !entry.isExpired();
|
||||
}
|
||||
|
||||
/**
|
||||
* Get cache statistics
|
||||
*/
|
||||
public Optional<Stats> getStats() {
|
||||
return Optional.ofNullable(stats);
|
||||
}
|
||||
|
||||
/**
|
||||
* Invalidate entries matching a pattern
|
||||
*/
|
||||
public void invalidatePattern(String pattern) {
|
||||
lock.writeLock().lock();
|
||||
try {
|
||||
List<K> keysToRemove = entries.keySet().stream()
|
||||
.filter(key -> key.toString().contains(pattern))
|
||||
.collect(ArrayList::new, ArrayList::add, ArrayList::addAll);
|
||||
|
||||
keysToRemove.forEach(this::remove);
|
||||
} finally {
|
||||
lock.writeLock().unlock();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all keys in the cache (expensive operation)
|
||||
*/
|
||||
public Set<K> keySet() {
|
||||
return new HashSet<>(entries.keySet());
|
||||
}
|
||||
|
||||
/**
|
||||
* Cleanup expired entries
|
||||
*/
|
||||
public void cleanupExpired() {
|
||||
lock.writeLock().lock();
|
||||
try {
|
||||
List<K> expiredKeys = entries.entrySet().stream()
|
||||
.filter(entry -> entry.getValue().isExpired())
|
||||
.map(Map.Entry::getKey)
|
||||
.collect(ArrayList::new, ArrayList::add, ArrayList::addAll);
|
||||
|
||||
expiredKeys.forEach(key -> {
|
||||
entries.remove(key);
|
||||
removeFromTracking(key);
|
||||
if (stats != null) {
|
||||
stats.recordEviction();
|
||||
}
|
||||
});
|
||||
|
||||
if (stats != null && !expiredKeys.isEmpty()) {
|
||||
stats.updateSize(entries.size());
|
||||
}
|
||||
} finally {
|
||||
lock.writeLock().unlock();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Shutdown the cache and cleanup resources
|
||||
*/
|
||||
public void shutdown() {
|
||||
cleanupExecutor.shutdown();
|
||||
try {
|
||||
if (!cleanupExecutor.awaitTermination(1, TimeUnit.SECONDS)) {
|
||||
cleanupExecutor.shutdownNow();
|
||||
}
|
||||
} catch (InterruptedException e) {
|
||||
cleanupExecutor.shutdownNow();
|
||||
Thread.currentThread().interrupt();
|
||||
}
|
||||
}
|
||||
|
||||
private void evictOne() {
|
||||
K keyToEvict = findEvictionCandidate();
|
||||
if (keyToEvict != null) {
|
||||
entries.remove(keyToEvict);
|
||||
removeFromTracking(keyToEvict);
|
||||
if (stats != null) {
|
||||
stats.recordEviction();
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private K findEvictionCandidate() {
|
||||
if (entries.isEmpty()) return null;
|
||||
|
||||
switch (config.getStrategy()) {
|
||||
case LRU:
|
||||
return findLruKey();
|
||||
case LFU:
|
||||
return findLfuKey();
|
||||
case FIFO:
|
||||
return findFifoKey();
|
||||
case TTL:
|
||||
return findEarliestExpirationKey();
|
||||
default:
|
||||
return findLruKey();
|
||||
}
|
||||
}
|
||||
|
||||
private K findLruKey() {
|
||||
synchronized (accessOrder) {
|
||||
return accessOrder.isEmpty() ? null : accessOrder.iterator().next();
|
||||
}
|
||||
}
|
||||
|
||||
private K findLfuKey() {
|
||||
return frequencyMap.entrySet().stream()
|
||||
.min(Map.Entry.comparingByValue())
|
||||
.map(Map.Entry::getKey)
|
||||
.orElse(null);
|
||||
}
|
||||
|
||||
private K findFifoKey() {
|
||||
return entries.entrySet().stream()
|
||||
.min(Map.Entry.comparingByValue(
|
||||
Comparator.comparing(entry -> entry.insertionOrder)))
|
||||
.map(Map.Entry::getKey)
|
||||
.orElse(null);
|
||||
}
|
||||
|
||||
private K findEarliestExpirationKey() {
|
||||
return entries.entrySet().stream()
|
||||
.min(Map.Entry.comparingByValue(
|
||||
Comparator.comparing(entry -> entry.expiration)))
|
||||
.map(Map.Entry::getKey)
|
||||
.orElse(null);
|
||||
}
|
||||
|
||||
private void updateAccessTracking(K key) {
|
||||
if (config.getStrategy() == Strategy.LRU) {
|
||||
synchronized (accessOrder) {
|
||||
accessOrder.remove(key);
|
||||
accessOrder.add(key);
|
||||
}
|
||||
}
|
||||
|
||||
if (config.getStrategy() == Strategy.LFU) {
|
||||
CacheEntry<V> entry = entries.get(key);
|
||||
if (entry != null) {
|
||||
frequencyMap.put(key, entry.accessCount);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private void updateInsertionTracking(K key) {
|
||||
if (config.getStrategy() == Strategy.LRU) {
|
||||
synchronized (accessOrder) {
|
||||
accessOrder.add(key);
|
||||
}
|
||||
}
|
||||
|
||||
if (config.getStrategy() == Strategy.LFU) {
|
||||
frequencyMap.put(key, 1L);
|
||||
}
|
||||
}
|
||||
|
||||
private void removeFromTracking(K key) {
|
||||
if (config.getStrategy() == Strategy.LRU) {
|
||||
synchronized (accessOrder) {
|
||||
accessOrder.remove(key);
|
||||
}
|
||||
}
|
||||
|
||||
if (config.getStrategy() == Strategy.LFU) {
|
||||
frequencyMap.remove(key);
|
||||
}
|
||||
}
|
||||
}
|
||||
401
sdks/java/src/main/java/dev/hcfs/sdk/HCFSError.java
Normal file
401
sdks/java/src/main/java/dev/hcfs/sdk/HCFSError.java
Normal file
@@ -0,0 +1,401 @@
|
||||
package dev.hcfs.sdk;
|
||||
|
||||
import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import java.time.Duration;
|
||||
|
||||
/**
|
||||
* Base exception class for all HCFS SDK errors.
|
||||
*
|
||||
* This class provides a comprehensive error hierarchy for handling
|
||||
* various failure modes when interacting with the HCFS API.
|
||||
*/
|
||||
public class HCFSError extends Exception {
|
||||
private final String errorCode;
|
||||
private final Map<String, Object> details;
|
||||
private final Integer statusCode;
|
||||
|
||||
public HCFSError(String message) {
|
||||
this(message, null, null, null);
|
||||
}
|
||||
|
||||
public HCFSError(String message, String errorCode) {
|
||||
this(message, errorCode, null, null);
|
||||
}
|
||||
|
||||
public HCFSError(String message, String errorCode, Map<String, Object> details, Integer statusCode) {
|
||||
super(message);
|
||||
this.errorCode = errorCode;
|
||||
this.details = details;
|
||||
this.statusCode = statusCode;
|
||||
}
|
||||
|
||||
public String getErrorCode() {
|
||||
return errorCode;
|
||||
}
|
||||
|
||||
public Map<String, Object> getDetails() {
|
||||
return details;
|
||||
}
|
||||
|
||||
public Integer getStatusCode() {
|
||||
return statusCode;
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if this error should trigger a retry
|
||||
*/
|
||||
public boolean isRetryable() {
|
||||
if (statusCode == null) return false;
|
||||
return statusCode >= 500 || statusCode == 429 ||
|
||||
this instanceof ConnectionError ||
|
||||
this instanceof TimeoutError;
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if this error is temporary
|
||||
*/
|
||||
public boolean isTemporary() {
|
||||
if (statusCode == null) return false;
|
||||
return statusCode == 429 || statusCode == 502 || statusCode == 503 || statusCode == 504 ||
|
||||
this instanceof TimeoutError ||
|
||||
this instanceof ConnectionError;
|
||||
}
|
||||
|
||||
/**
|
||||
* Connection error - network issues, DNS resolution, etc.
|
||||
*/
|
||||
public static class ConnectionError extends HCFSError {
|
||||
public ConnectionError(String message) {
|
||||
super(message, "CONNECTION_FAILED");
|
||||
}
|
||||
|
||||
public ConnectionError(String message, Throwable cause) {
|
||||
super(message, "CONNECTION_FAILED");
|
||||
initCause(cause);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Authentication failure
|
||||
*/
|
||||
public static class AuthenticationError extends HCFSError {
|
||||
public AuthenticationError(String message) {
|
||||
super(message, "AUTH_FAILED", null, 401);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Authorization failure - insufficient permissions
|
||||
*/
|
||||
public static class AuthorizationError extends HCFSError {
|
||||
public AuthorizationError(String message) {
|
||||
super(message, "INSUFFICIENT_PERMISSIONS", null, 403);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Resource not found error
|
||||
*/
|
||||
public static class NotFoundError extends HCFSError {
|
||||
private final String resourceType;
|
||||
private final String resourceId;
|
||||
|
||||
public NotFoundError(String message) {
|
||||
this(message, null, null);
|
||||
}
|
||||
|
||||
public NotFoundError(String message, String resourceType, String resourceId) {
|
||||
super(message, "NOT_FOUND", null, 404);
|
||||
this.resourceType = resourceType;
|
||||
this.resourceId = resourceId;
|
||||
}
|
||||
|
||||
public String getResourceType() {
|
||||
return resourceType;
|
||||
}
|
||||
|
||||
public String getResourceId() {
|
||||
return resourceId;
|
||||
}
|
||||
|
||||
@Override
|
||||
public String getMessage() {
|
||||
StringBuilder msg = new StringBuilder(super.getMessage());
|
||||
if (resourceType != null) {
|
||||
msg.append(" (type: ").append(resourceType).append(")");
|
||||
}
|
||||
if (resourceId != null) {
|
||||
msg.append(" (id: ").append(resourceId).append(")");
|
||||
}
|
||||
return msg.toString();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Request validation error
|
||||
*/
|
||||
public static class ValidationError extends HCFSError {
|
||||
private final List<ValidationDetail> validationErrors;
|
||||
|
||||
public ValidationError(String message, List<ValidationDetail> validationErrors) {
|
||||
super(message, "VALIDATION_FAILED", null, 400);
|
||||
this.validationErrors = validationErrors;
|
||||
}
|
||||
|
||||
public List<ValidationDetail> getValidationErrors() {
|
||||
return validationErrors;
|
||||
}
|
||||
|
||||
@Override
|
||||
public String getMessage() {
|
||||
if (validationErrors != null && !validationErrors.isEmpty()) {
|
||||
return super.getMessage() + " (" + validationErrors.size() + " validation issues)";
|
||||
}
|
||||
return super.getMessage();
|
||||
}
|
||||
|
||||
public static class ValidationDetail {
|
||||
@JsonProperty("field")
|
||||
private String field;
|
||||
|
||||
@JsonProperty("message")
|
||||
private String message;
|
||||
|
||||
@JsonProperty("code")
|
||||
private String code;
|
||||
|
||||
public ValidationDetail() {}
|
||||
|
||||
public ValidationDetail(String field, String message, String code) {
|
||||
this.field = field;
|
||||
this.message = message;
|
||||
this.code = code;
|
||||
}
|
||||
|
||||
public String getField() { return field; }
|
||||
public void setField(String field) { this.field = field; }
|
||||
|
||||
public String getMessage() { return message; }
|
||||
public void setMessage(String message) { this.message = message; }
|
||||
|
||||
public String getCode() { return code; }
|
||||
public void setCode(String code) { this.code = code; }
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Rate limiting error
|
||||
*/
|
||||
public static class RateLimitError extends HCFSError {
|
||||
private final Duration retryAfter;
|
||||
|
||||
public RateLimitError(String message) {
|
||||
this(message, null);
|
||||
}
|
||||
|
||||
public RateLimitError(String message, Duration retryAfter) {
|
||||
super(buildMessage(message, retryAfter), "RATE_LIMIT_EXCEEDED", null, 429);
|
||||
this.retryAfter = retryAfter;
|
||||
}
|
||||
|
||||
public Duration getRetryAfter() {
|
||||
return retryAfter;
|
||||
}
|
||||
|
||||
private static String buildMessage(String message, Duration retryAfter) {
|
||||
if (retryAfter != null) {
|
||||
return message + ". Retry after " + retryAfter.getSeconds() + " seconds";
|
||||
}
|
||||
return message;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Server-side error (5xx status codes)
|
||||
*/
|
||||
public static class ServerError extends HCFSError {
|
||||
public ServerError(String message, int statusCode) {
|
||||
super(message, "SERVER_ERROR", null, statusCode);
|
||||
}
|
||||
|
||||
@Override
|
||||
public String getMessage() {
|
||||
return "Server error (HTTP " + getStatusCode() + "): " + super.getMessage();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Request timeout error
|
||||
*/
|
||||
public static class TimeoutError extends HCFSError {
|
||||
private final Duration timeout;
|
||||
|
||||
public TimeoutError(String message) {
|
||||
this(message, null);
|
||||
}
|
||||
|
||||
public TimeoutError(String message, Duration timeout) {
|
||||
super(buildMessage(message, timeout), "TIMEOUT");
|
||||
this.timeout = timeout;
|
||||
}
|
||||
|
||||
public Duration getTimeout() {
|
||||
return timeout;
|
||||
}
|
||||
|
||||
private static String buildMessage(String message, Duration timeout) {
|
||||
if (timeout != null) {
|
||||
return message + " after " + timeout.toMillis() + "ms";
|
||||
}
|
||||
return message;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Cache operation error
|
||||
*/
|
||||
public static class CacheError extends HCFSError {
|
||||
private final String operation;
|
||||
|
||||
public CacheError(String message) {
|
||||
this(message, null);
|
||||
}
|
||||
|
||||
public CacheError(String message, String operation) {
|
||||
super(message, "CACHE_ERROR");
|
||||
this.operation = operation;
|
||||
}
|
||||
|
||||
public String getOperation() {
|
||||
return operation;
|
||||
}
|
||||
|
||||
@Override
|
||||
public String getMessage() {
|
||||
if (operation != null) {
|
||||
return "Cache error during " + operation + ": " + super.getMessage();
|
||||
}
|
||||
return "Cache error: " + super.getMessage();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Batch operation error
|
||||
*/
|
||||
public static class BatchError extends HCFSError {
|
||||
private final List<BatchFailureItem> failedItems;
|
||||
|
||||
public BatchError(String message, List<BatchFailureItem> failedItems) {
|
||||
super(message, "BATCH_ERROR");
|
||||
this.failedItems = failedItems;
|
||||
}
|
||||
|
||||
public List<BatchFailureItem> getFailedItems() {
|
||||
return failedItems;
|
||||
}
|
||||
|
||||
@Override
|
||||
public String getMessage() {
|
||||
if (failedItems != null && !failedItems.isEmpty()) {
|
||||
return super.getMessage() + " (" + failedItems.size() + " failed items)";
|
||||
}
|
||||
return super.getMessage();
|
||||
}
|
||||
|
||||
public static class BatchFailureItem {
|
||||
@JsonProperty("index")
|
||||
private int index;
|
||||
|
||||
@JsonProperty("error")
|
||||
private String error;
|
||||
|
||||
@JsonProperty("item")
|
||||
private Object item;
|
||||
|
||||
public BatchFailureItem() {}
|
||||
|
||||
public BatchFailureItem(int index, String error, Object item) {
|
||||
this.index = index;
|
||||
this.error = error;
|
||||
this.item = item;
|
||||
}
|
||||
|
||||
public int getIndex() { return index; }
|
||||
public void setIndex(int index) { this.index = index; }
|
||||
|
||||
public String getError() { return error; }
|
||||
public void setError(String error) { this.error = error; }
|
||||
|
||||
public Object getItem() { return item; }
|
||||
public void setItem(Object item) { this.item = item; }
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Search operation error
|
||||
*/
|
||||
public static class SearchError extends HCFSError {
|
||||
private final String query;
|
||||
private final String searchType;
|
||||
|
||||
public SearchError(String message) {
|
||||
this(message, null, null);
|
||||
}
|
||||
|
||||
public SearchError(String message, String query, String searchType) {
|
||||
super(message, "SEARCH_ERROR");
|
||||
this.query = query;
|
||||
this.searchType = searchType;
|
||||
}
|
||||
|
||||
public String getQuery() {
|
||||
return query;
|
||||
}
|
||||
|
||||
public String getSearchType() {
|
||||
return searchType;
|
||||
}
|
||||
|
||||
@Override
|
||||
public String getMessage() {
|
||||
StringBuilder msg = new StringBuilder("Search error: ").append(super.getMessage());
|
||||
if (searchType != null) {
|
||||
msg.append(" (type: ").append(searchType).append(")");
|
||||
}
|
||||
if (query != null) {
|
||||
msg.append(" (query: '").append(query).append("')");
|
||||
}
|
||||
return msg.toString();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* WebSocket/streaming error
|
||||
*/
|
||||
public static class StreamError extends HCFSError {
|
||||
public StreamError(String message) {
|
||||
super(message, "STREAM_ERROR");
|
||||
}
|
||||
|
||||
public StreamError(String message, Throwable cause) {
|
||||
super(message, "STREAM_ERROR");
|
||||
initCause(cause);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* JSON serialization/deserialization error
|
||||
*/
|
||||
public static class SerializationError extends HCFSError {
|
||||
public SerializationError(String message) {
|
||||
super(message, "SERIALIZATION_ERROR");
|
||||
}
|
||||
|
||||
public SerializationError(String message, Throwable cause) {
|
||||
super(message, "SERIALIZATION_ERROR");
|
||||
initCause(cause);
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user