Skip to main content

Java SDK Tutorial

This tutorial will guide you through using the Cloakr.ai SDK in Java applications, from basic setup to advanced features.

Installation​

Prerequisites​

  • Java 11+
  • Maven or Gradle

Maven Dependency​

<dependency>
    <groupId>ai.cloakr</groupId>
    <artifactId>cloakr-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle Dependency​

implementation 'ai.cloakr:cloakr-sdk:1.0.0'

Basic Setup​

Initialize the Client​

import ai.cloakr.CloakrClient;
import ai.cloakr.config.ClientConfig;

public class CloakrExample {
    public static void main(String[] args) {
        ClientConfig config = ClientConfig.builder()
            .apiKey(System.getenv("CLOAKR_API_KEY"))
            .encryption(true)
            .piiDetection(true)
            .retryAttempts(3)
            .timeout(Duration.ofSeconds(30))
            .build();
        
        CloakrClient client = new CloakrClient(config);
    }
}

Environment Variables​

Set environment variables in your system or use a .env file:

CLOAKR_API_KEY=your-api-key-here
CLOAKR_ENCRYPTION_KEY=your-encryption-key-here  # Optional
CLOAKR_KEY_ID=your-key-id-here                  # Optional

Basic Usage​

Simple Chat Request​

import ai.cloakr.CloakrClient;
import ai.cloakr.models.ChatRequest;
import ai.cloakr.models.ChatResponse;

public class SimpleChatExample {
    public static void main(String[] args) {
        CloakrClient client = new CloakrClient(
            System.getenv("CLOAKR_API_KEY")
        );
        
        try {
            ChatRequest request = ChatRequest.builder()
                .model("gpt-4o")
                .prompt("What is Cloakr.ai?")
                .maxTokens(1000)
                .temperature(0.7)
                .build();
            
            ChatResponse response = client.chat(request);
            System.out.println(response.getChoices().get(0).getText());
            
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}

Async Chat Request​

import ai.cloakr.CloakrClient;
import ai.cloakr.models.ChatRequest;
import ai.cloakr.models.ChatResponse;
import java.util.concurrent.CompletableFuture;

public class AsyncChatExample {
    public static void main(String[] args) {
        CloakrClient client = new CloakrClient(
            System.getenv("CLOAKR_API_KEY")
        );
        
        ChatRequest request = ChatRequest.builder()
            .model("gpt-4o")
            .prompt("What is Cloakr.ai?")
            .build();
        
        CompletableFuture<ChatResponse> future = client.chatAsync(request);
        
        future.thenAccept(response -> {
            System.out.println(response.getChoices().get(0).getText());
        }).exceptionally(throwable -> {
            System.err.println("Error: " + throwable.getMessage());
            return null;
        });
        
        // Wait for completion
        future.join();
    }
}

Streaming Responses​

import ai.cloakr.CloakrClient;
import ai.cloakr.models.ChatRequest;
import ai.cloakr.models.ChatChunk;

public class StreamingChatExample {
    public static void main(String[] args) {
        CloakrClient client = new CloakrClient(
            System.getenv("CLOAKR_API_KEY")
        );
        
        ChatRequest request = ChatRequest.builder()
            .model("gpt-4o")
            .prompt("Write a story about AI security")
            .stream(true)
            .build();
        
        try {
            client.chatStream(request).forEach(chunk -> {
                if (chunk.getChoices().get(0).getDelta() != null &&
                    chunk.getChoices().get(0).getDelta().getText() != null) {
                    System.out.print(chunk.getChoices().get(0).getDelta().getText());
                }
            });
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}

Advanced Features​

Custom PII Redaction​

import ai.cloakr.CloakrClient;
import ai.cloakr.pii.PIIRedactor;
import ai.cloakr.pii.RedactionRule;
import java.util.Arrays;

public class PIIRedactionExample {
    public static void main(String[] args) {
        CloakrClient client = new CloakrClient(
            System.getenv("CLOAKR_API_KEY")
        );
        
        // Custom redaction rules
        RedactionRule customRule = RedactionRule.builder()
            .type("custom_pattern")
            .pattern("CUSTOMER-\\d{6}")
            .replacement("[REDACTED_CUSTOMER_ID]")
            .build();
        
        RedactionRule emailRule = RedactionRule.builder()
            .type("email")
            .domains(Arrays.asList("internal.com", "test.com"))
            .build();
        
        PIIRedactor redactor = PIIRedactor.builder()
            .rules(Arrays.asList(customRule, emailRule))
            .build();
        
        client.setPIIRedactor(redactor);
    }
}

Encryption Configuration​

import ai.cloakr.CloakrClient;
import ai.cloakr.encryption.EncryptionConfig;

public class EncryptionExample {
    public static void main(String[] args) {
        EncryptionConfig encryptionConfig = EncryptionConfig.builder()
            .algorithm("AES-256-GCM")
            .keyId(System.getenv("CLOAKR_KEY_ID"))
            .keyRotation(true)
            .compression(true)
            .build();
        
        CloakrClient client = CloakrClient.builder()
            .apiKey(System.getenv("CLOAKR_API_KEY"))
            .encryption(encryptionConfig)
            .build();
    }
}

Retry Logic with Exponential Backoff​

import ai.cloakr.CloakrClient;
import ai.cloakr.retry.RetryConfig;
import java.time.Duration;
import java.util.Arrays;

public class RetryExample {
    public static void main(String[] args) {
        RetryConfig retryConfig = RetryConfig.builder()
            .maxAttempts(5)
            .baseDelay(Duration.ofSeconds(1))
            .maxDelay(Duration.ofSeconds(30))
            .backoffMultiplier(2.0)
            .retryableErrors(Arrays.asList("rate_limit_exceeded", "internal_error"))
            .build();
        
        CloakrClient client = CloakrClient.builder()
            .apiKey(System.getenv("CLOAKR_API_KEY"))
            .retry(retryConfig)
            .build();
    }
}

Error Handling​

Comprehensive Error Handling​

import ai.cloakr.CloakrClient;
import ai.cloakr.exceptions.CloakrException;
import ai.cloakr.models.ChatRequest;
import ai.cloakr.models.ChatResponse;

public class ErrorHandlingExample {
    public static void main(String[] args) {
        CloakrClient client = new CloakrClient(
            System.getenv("CLOAKR_API_KEY")
        );
        
        try {
            ChatRequest request = ChatRequest.builder()
                .model("gpt-4o")
                .prompt("Hello world")
                .build();
            
            ChatResponse response = client.chat(request);
            return response;
            
        } catch (CloakrException e) {
            switch (e.getCode()) {
                case "rate_limit_exceeded":
                    System.out.println("Rate limited. Retry after " + e.getRetryAfter() + " seconds");
                    // Implement retry logic
                    break;
                    
                case "invalid_api_key":
                    System.err.println("Invalid API key. Check your configuration.");
                    break;
                    
                case "content_policy_violation":
                    System.err.println("Content violates usage policies: " + e.getDetails());
                    break;
                    
                default:
                    System.err.println("Unexpected error: " + e.getMessage());
            }
            throw e;
        } catch (Exception e) {
            System.err.println("Network or other error: " + e.getMessage());
            throw e;
        }
    }
}

Custom Error Handler​

import ai.cloakr.exceptions.CloakrException;
import java.time.LocalDateTime;
import java.util.logging.Logger;

public class CustomErrorHandler {
    private static final Logger logger = Logger.getLogger(CustomErrorHandler.class.getName());
    
    public static void handle(CloakrException error, String context) {
        logger.severe("Cloakr Error: " + Map.of(
            "code", error.getCode(),
            "message", error.getMessage(),
            "context", context,
            "timestamp", LocalDateTime.now().toString()
        ));
        
        // Log to external service
        logToExternalService(error, context);
        
        // Notify team if critical
        if ("internal_error".equals(error.getCode())) {
            notifyTeam(error, context);
        }
    }
    
    private static void logToExternalService(CloakrException error, String context) {
        // Implementation for external logging
    }
    
    private static void notifyTeam(CloakrException error, String context) {
        // Implementation for team notification
    }
}

Performance Optimization​

Connection Pooling​

import ai.cloakr.CloakrClient;
import ai.cloakr.connection.ConnectionPool;
import java.time.Duration;

public class ConnectionPoolExample {
    public static void main(String[] args) {
        ConnectionPool pool = ConnectionPool.builder()
            .maxConnections(10)
            .maxIdleTime(Duration.ofSeconds(30))
            .connectionTimeout(Duration.ofSeconds(5))
            .build();
        
        CloakrClient client = CloakrClient.builder()
            .apiKey(System.getenv("CLOAKR_API_KEY"))
            .connectionPool(pool)
            .build();
    }
}

Request Batching​

import ai.cloakr.CloakrClient;
import ai.cloakr.models.ChatRequest;
import ai.cloakr.models.ChatResponse;
import java.util.List;
import java.util.concurrent.CompletableFuture;
import java.util.stream.Collectors;

public class BatchRequestExample {
    public static void main(String[] args) {
        CloakrClient client = new CloakrClient(
            System.getenv("CLOAKR_API_KEY")
        );
        
        List<String> prompts = Arrays.asList(
            "What is AI?",
            "What is machine learning?",
            "What is deep learning?"
        );
        
        List<CompletableFuture<ChatResponse>> futures = prompts.stream()
            .map(prompt -> {
                ChatRequest request = ChatRequest.builder()
                    .model("gpt-4o")
                    .prompt(prompt)
                    .build();
                return client.chatAsync(request);
            })
            .collect(Collectors.toList());
        
        // Wait for all requests to complete
        List<ChatResponse> responses = futures.stream()
            .map(CompletableFuture::join)
            .collect(Collectors.toList());
        
        responses.forEach(response -> 
            System.out.println(response.getChoices().get(0).getText())
        );
    }
}

Caching​

import ai.cloakr.CloakrClient;
import ai.cloakr.cache.CacheManager;
import java.time.Duration;

public class CachingExample {
    public static void main(String[] args) {
        CacheManager cache = CacheManager.builder()
            .ttl(Duration.ofHours(1))
            .maxSize(1000)
            .strategy("lru")
            .build();
        
        CloakrClient client = CloakrClient.builder()
            .apiKey(System.getenv("CLOAKR_API_KEY"))
            .cache(cache)
            .build();
    }
}

Testing​

Unit Tests with JUnit​

import ai.cloakr.CloakrClient;
import ai.cloakr.models.ChatRequest;
import ai.cloakr.models.ChatResponse;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.BeforeEach;
import static org.junit.jupiter.api.Assertions.*;
import static org.mockito.Mockito.*;

public class ChatServiceTest {
    private CloakrClient client;
    
    @BeforeEach
    void setUp() {
        client = new CloakrClient("test-key");
    }
    
    @Test
    void testSuccessfulChatRequest() {
        // Mock the client
        CloakrClient mockClient = mock(CloakrClient.class);
        
        ChatResponse mockResponse = ChatResponse.builder()
            .choices(Arrays.asList(
                ChatChoice.builder()
                    .text("Mock response")
                    .build()
            ))
            .build();
        
        when(mockClient.chat(any(ChatRequest.class)))
            .thenReturn(mockResponse);
        
        ChatRequest request = ChatRequest.builder()
            .model("gpt-4o")
            .prompt("Test prompt")
            .build();
        
        ChatResponse result = mockClient.chat(request);
        
        assertEquals("Mock response", result.getChoices().get(0).getText());
    }
    
    @Test
    void testRateLimitError() {
        CloakrClient mockClient = mock(CloakrClient.class);
        
        CloakrException mockError = new CloakrException("Rate limit exceeded");
        mockError.setCode("rate_limit_exceeded");
        mockError.setRetryAfter(60);
        
        when(mockClient.chat(any(ChatRequest.class)))
            .thenThrow(mockError);
        
        ChatRequest request = ChatRequest.builder()
            .model("gpt-4o")
            .prompt("Test prompt")
            .build();
        
        assertThrows(CloakrException.class, () -> {
            mockClient.chat(request);
        });
    }
}

Integration Tests​

import ai.cloakr.CloakrClient;
import ai.cloakr.models.ChatRequest;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.BeforeEach;
import static org.junit.jupiter.api.Assertions.*;

public class CloakrIntegrationTest {
    private CloakrClient client;
    
    @BeforeEach
    void setUp() {
        client = new CloakrClient(System.getenv("CLOAKR_TEST_API_KEY"));
    }
    
    @Test
    void testChatRequest() {
        ChatRequest request = ChatRequest.builder()
            .model("gpt-4o")
            .prompt("Hello, this is a test")
            .maxTokens(50)
            .build();
        
        ChatResponse response = client.chat(request);
        
        assertNotNull(response.getChoices());
        assertNotNull(response.getChoices().get(0).getText());
        assertFalse(response.getChoices().get(0).getText().isEmpty());
    }
}

Production Best Practices​

Environment Configuration​

import ai.cloakr.CloakrClient;
import ai.cloakr.config.ClientConfig;
import java.time.Duration;

public class EnvironmentConfig {
    public static ClientConfig getConfig() {
        String env = System.getenv("NODE_ENV");
        if (env == null) env = "development";
        
        switch (env) {
            case "production":
                return ClientConfig.builder()
                    .apiKey(System.getenv("CLOAKR_PROD_API_KEY"))
                    .encryption(true)
                    .retryAttempts(3)
                    .timeout(Duration.ofSeconds(30))
                    .build();
                    
            default: // development
                return ClientConfig.builder()
                    .apiKey(System.getenv("CLOAKR_DEV_API_KEY"))
                    .encryption(false)
                    .retryAttempts(1)
                    .build();
        }
    }
}

Monitoring and Logging​

import ai.cloakr.CloakrClient;
import ai.cloakr.metrics.MetricsCollector;
import java.util.logging.Logger;

public class MonitoringExample {
    private static final Logger logger = Logger.getLogger(MonitoringExample.class.getName());
    
    public static void main(String[] args) {
        MetricsCollector metrics = new MetricsCollector() {
            @Override
            public void increment(String metric, int value) {
                logger.info("Metric: " + metric + " = " + value);
            }
            
            @Override
            public void timing(String metric, long duration) {
                logger.info("Timing: " + metric + " = " + duration + "ms");
            }
        };
        
        CloakrClient client = CloakrClient.builder()
            .apiKey(System.getenv("CLOAKR_API_KEY"))
            .metrics(metrics)
            .build();
        
        // Custom metrics
        client.onRequest(data -> {
            metrics.increment("cloakr.requests.total");
            metrics.timing("cloakr.requests.duration", data.getDuration());
        });
        
        client.onError(error -> {
            metrics.increment("cloakr.errors.total");
            metrics.increment("cloakr.errors." + error.getCode());
        });
    }
}

Security Considerations​

import ai.cloakr.CloakrClient;
import java.util.regex.Pattern;

public class SecurityExample {
    public static void main(String[] args) {
        // Validate API key format
        String apiKey = validateApiKey(System.getenv("CLOAKR_API_KEY"));
        
        CloakrClient client = CloakrClient.builder()
            .apiKey(apiKey)
            .encryption(true)
            .piiDetection(true)
            .build();
    }
    
    private static String validateApiKey(String apiKey) {
        if (apiKey == null || apiKey.isEmpty()) {
            throw new IllegalArgumentException("API key must be a non-empty string");
        }
        
        if (!apiKey.startsWith("cloakr_")) {
            throw new IllegalArgumentException("Invalid API key format");
        }
        
        return apiKey;
    }
}

Spring Boot Integration​

import ai.cloakr.CloakrClient;
import ai.cloakr.models.ChatRequest;
import ai.cloakr.models.ChatResponse;
import org.springframework.web.bind.annotation.*;
import org.springframework.stereotype.Service;

@Service
public class ChatService {
    private final CloakrClient client;
    
    public ChatService() {
        this.client = new CloakrClient(System.getenv("CLOAKR_API_KEY"));
    }
    
    public ChatResponse chat(String prompt, String model) {
        ChatRequest request = ChatRequest.builder()
            .model(model != null ? model : "gpt-4o")
            .prompt(prompt)
            .maxTokens(1000)
            .temperature(0.7)
            .build();
        
        return client.chat(request);
    }
}

@RestController
@RequestMapping("/api/chat")
public class ChatController {
    private final ChatService chatService;
    
    public ChatController(ChatService chatService) {
        this.chatService = chatService;
    }
    
    @PostMapping
    public ChatResponse chat(@RequestBody ChatRequestDto request) {
        return chatService.chat(request.getPrompt(), request.getModel());
    }
}

class ChatRequestDto {
    private String prompt;
    private String model;
    
    // Getters and setters
    public String getPrompt() { return prompt; }
    public void setPrompt(String prompt) { this.prompt = prompt; }
    public String getModel() { return model; }
    public void setModel(String model) { this.model = model; }
}

Next Steps​