Java SDK — PrivaiShield

Java SDK

The official PrivaiShield SDK for Java. Enterprise-grade SDK with builder pattern, reactive streams, and Spring Boot integration.

View on Maven Central GitHub

Installation

Add the SDK to your project using Maven or Gradle.

Gradle (Kotlin DSL)kotlin

implementation("com.privaishield:sdk:1.0.0")

Gradle (Groovy)groovy

implementation 'com.privaishield:sdk:1.0.0'

Mavenxml

<dependency>
    <groupId>com.privaishield</groupId>
    <artifactId>sdk</artifactId>
    <version>1.0.0</version>
</dependency>

Requirements

Java 11+ (Java 17+ recommended)
OkHttp 4.x (included)
Jackson 2.x (included)

Quick Start

Initialize the client with your API key and make your first request.

Basic Usagejava

import com.privaishield.PrivaiShield;
import com.privaishield.model.RedactResult;
import com.privaishield.model.Entity;

public class Example {
    public static void main(String[] args) {
        // Initialize the client
        PrivaiShield client = PrivaiShield.builder()
            .apiKey(System.getenv("PRIVAISHIELD_API_KEY"))
            .build();

        // Redact PII from text
        RedactResult result = client.redact()
            .text("Contact John Smith at john@acme.com or 555-123-4567")
            .mode("enhanced")
            .execute();

        System.out.println(result.getRedacted());
        // "Contact [PERSON_1] at [EMAIL_1] or [PHONE_1]"

        for (Entity entity : result.getEntities()) {
            System.out.printf("%s: %s (%.2f)%n",
                entity.getType(),
                entity.getToken(),
                entity.getConfidence()
            );
        }
    }
}

Environment Variablebash

export PRIVAISHIELD_API_KEY=sk_live_your_key_here

Builder Pattern

The SDK uses the builder pattern throughout for fluent, readable API calls.

Client Configurationjava

PrivaiShield client = PrivaiShield.builder()
    .apiKey(apiKey)
    .baseUrl("https://api.privaishield.com/v1")  // Optional
    .timeout(Duration.ofSeconds(30))             // Optional
    .maxRetries(3)                               // Optional
    .httpClient(customOkHttpClient)              // Optional
    .build();

Redact Requestjava

RedactResult result = client.redact()
    .text("Contact john@example.com")
    .mode("enhanced")
    .entities(List.of("PERSON", "EMAIL", "PHONE"))
    .confidence(0.8)
    .returnOriginal(true)
    .execute();

Document Processingjava

DocumentResult result = client.redactDocument()
    .file(new File("contract.pdf"))
    .mode("enhanced")
    .outputFormat("pdf")
    .execute();

// Download redacted document
client.downloadDocument(result.getDocumentId(), outputPath);

Batch Processingjava

List<BatchItem> items = List.of(
    new BatchItem("1", "Email: john@example.com"),
    new BatchItem("2", "Phone: 555-123-4567"),
    new BatchItem("3", "SSN: 123-45-6789")
);

BatchResult result = client.redactBatch()
    .items(items)
    .mode("enhanced")
    .execute();

for (BatchItemResult item : result.getResults()) {
    System.out.printf("%s: %s%n", item.getId(), item.getRedacted());
}

Reactive Streams

The SDK supports reactive streams using Project Reactor for non-blocking operations.

Add Reactor Dependencygroovy

implementation 'com.privaishield:sdk-reactor:1.0.0'

Reactive Clientjava

import com.privaishield.reactor.ReactivePrivaiShield;
import reactor.core.publisher.Mono;
import reactor.core.publisher.Flux;

ReactivePrivaiShield client = ReactivePrivaiShield.builder()
    .apiKey(apiKey)
    .build();

// Single async redaction
Mono<RedactResult> result = client.redact()
    .text("Email: john@example.com")
    .execute();

result.subscribe(r -> System.out.println(r.getRedacted()));

Streaming Eventsjava

Flux<RedactEvent> events = client.redactStream()
    .text(longDocument)
    .mode("enhanced")
    .execute();

events.subscribe(event -> {
    switch (event.getType()) {
        case ENTITY:
            System.out.println("Found: " + event.getEntity().getType());
            break;
        case PROGRESS:
            System.out.printf("Progress: %d/%d%n",
                event.getProgress().getProcessed(),
                event.getProgress().getTotal()
            );
            break;
        case COMPLETE:
            System.out.println("Done: " + event.getResult().getRedacted());
            break;
    }
});

Batch with Backpressurejava

List<String> texts = // thousands of texts...

Flux.fromIterable(texts)
    .buffer(100)  // Batch in groups of 100
    .flatMap(batch -> {
        List<BatchItem> items = IntStream.range(0, batch.size())
            .mapToObj(i -> new BatchItem(String.valueOf(i), batch.get(i)))
            .toList();
        return client.redactBatch().items(items).execute();
    }, 4)  // 4 concurrent batches
    .flatMapIterable(BatchResult::getResults)
    .subscribe(item -> System.out.println(item.getRedacted()));

API Reference

Complete reference for all SDK classes and methods.

class PrivaiShield

Main client class for synchronous API calls.

redact()→ RedactRequestCreate text redaction request

redactDocument()→ DocumentRequestCreate document processing request

redactBatch()→ BatchRequestCreate batch processing request

getEntities()→ List<EntityType>List available entity types

getUsage()→ UsageResultGet API usage statistics

close()→ voidClose HTTP client connections

class RedactResult

Result of a text redaction operation.

public class RedactResult {
    public String getRedacted();
    public List<Entity> getEntities();
    public String getMode();
    public String getProcessingTime();
}

public class Entity {
    public String getType();
    public String getToken();
    public int getStart();
    public int getEnd();
    public double getConfidence();
    public Optional<String> getOriginal();
}

Spring Boot StarterOptional

Auto-configuration for Spring Boot applications.

Add Dependencygroovy

implementation 'com.privaishield:sdk-spring-boot-starter:1.0.0'

application.ymlyaml

privaishield:
  api-key: ${PRIVAISHIELD_API_KEY}
  timeout: 30s
  max-retries: 3

Inject Clientjava

@Service
public class RedactionService {
    private final PrivaiShield client;

    public RedactionService(PrivaiShield client) {
        this.client = client;
    }

    public String redact(String text) {
        return client.redact()
            .text(text)
            .mode("enhanced")
            .execute()
            .getRedacted();
    }
}

Error Handling

import com.privaishield.exception.*;

try {
    RedactResult result = client.redact()
        .text("...")
        .execute();
} catch (AuthenticationException e) {
    System.out.println("Invalid API key");
} catch (RateLimitException e) {
    System.out.printf("Rate limited. Retry after %d seconds%n",
        e.getRetryAfter());
} catch (ValidationException e) {
    System.out.printf("Invalid request: %s (param: %s)%n",
        e.getMessage(), e.getParam());
} catch (PrivaiShieldException e) {
    System.out.printf("API error: %s - %s%n",
        e.getCode(), e.getMessage());
}

REST API

Full API reference

Entity Types

Custom patterns & config