MACRO NEPAL
Sanity.io Java Client: Complete Implementation Guide
awiskar acharya
November 21, 2025
2:26 pm

Introduction to Sanity.io Java Client

Sanity.io is a headless CMS platform that provides real-time content management. This guide covers building a comprehensive Java client for interacting with Sanity.io's APIs, including content querying, mutations, real-time subscriptions, and asset management.

Key Features

  • Content Querying with GROQ (Graph-Relational Object Queries)
  • Real-time Subscriptions for live content updates
  • Asset Management for file uploads and transformations
  • Mutation Operations for creating, updating, and deleting content
  • Type-safe Models for Java integration
  • Error Handling and retry mechanisms

Dependencies and Setup

Maven Configuration

<properties>
<okhttp.version>4.12.0</okhttp.version>
<jackson.version>2.15.2</jackson.version>
<websocket.version>1.5.3</websocket.version>
</properties>
<dependencies>
<!-- HTTP Client -->
<dependency>
<groupId>com.squareup.okhttp3</groupId>
<artifactId>okhttp</artifactId>
<version>${okhttp.version}</version>
</dependency>
<dependency>
<groupId>com.squareup.okhttp3</groupId>
<artifactId>okhttp-sse</artifactId>
<version>${okhttp.version}</version>
</dependency>
<!-- WebSocket Client -->
<dependency>
<groupId>org.java-websocket</groupId>
<artifactId>Java-WebSocket</artifactId>
<version>${websocket.version}</version>
</dependency>
<!-- JSON Processing -->
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-core</artifactId>
<version>${jackson.version}</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>${jackson.version}</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-annotations</artifactId>
<version>${jackson.version}</version>
</dependency>
<!-- Logging -->
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-api</artifactId>
<version>2.0.7</version>
</dependency>
<!-- Testing -->
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter</artifactId>
<version>5.9.3</version>
<scope>test</scope>
</dependency>
<!-- Mock Web Server for Testing -->
<dependency>
<groupId>com.squareup.okhttp3</groupId>
<artifactId>mockwebserver</artifactId>
<version>${okhttp.version}</version>
<scope>test</scope>
</dependency>
</dependencies>

Core Sanity Client Implementation

Main Sanity Client

package com.sanity.client;
import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.ObjectMapper;
import okhttp3.*;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.io.IOException;
import java.util.*;
import java.util.concurrent.TimeUnit;
public class SanityClient {
private static final Logger logger = LoggerFactory.getLogger(SanityClient.class);
private final String projectId;
private final String dataset;
private final String token;
private final boolean useCdn;
private final OkHttpClient httpClient;
private final ObjectMapper objectMapper;
private final String baseUrl;
public SanityClient(String projectId, String dataset, String token) {
this(projectId, dataset, token, true);
}
public SanityClient(String projectId, String dataset, String token, boolean useCdn) {
this.projectId = projectId;
this.dataset = dataset;
this.token = token;
this.useCdn = useCdn;
this.objectMapper = new ObjectMapper();
this.httpClient = new OkHttpClient.Builder()
.connectTimeout(30, TimeUnit.SECONDS)
.readTimeout(60, TimeUnit.SECONDS)
.writeTimeout(30, TimeUnit.SECONDS)
.build();
this.baseUrl = useCdn ? 
"https://" + projectId + ".apicdn.sanity.io/v1" :
"https://" + projectId + ".api.sanity.io/v1";
}
/**
* Execute GROQ query and return typed results
*/
public <T> QueryResponse<T> query(String groqQuery, Class<T> resultType) throws SanityException {
return query(groqQuery, Collections.emptyMap(), resultType);
}
/**
* Execute GROQ query with parameters
*/
public <T> QueryResponse<T> query(String groqQuery, Map<String, Object> params, Class<T> resultType) throws SanityException {
try {
// Build request URL
HttpUrl.Builder urlBuilder = HttpUrl.parse(baseUrl + "/data/query/" + dataset).newBuilder();
urlBuilder.addQueryParameter("query", groqQuery);
// Add parameters as JSON
if (params != null && !params.isEmpty()) {
String paramsJson = objectMapper.writeValueAsString(params);
urlBuilder.addQueryParameter("$params", paramsJson);
}
Request request = createAuthenticatedRequest()
.url(urlBuilder.build())
.get()
.build();
try (Response response = httpClient.newCall(request).execute()) {
return parseQueryResponse(response, resultType);
}
} catch (IOException e) {
throw new SanityException("Query execution failed", e);
}
}
/**
* Execute GROQ query returning list of results
*/
public <T> QueryResponse<List<T>> queryList(String groqQuery, Class<T> elementType) throws SanityException {
return queryList(groqQuery, Collections.emptyMap(), elementType);
}
public <T> QueryResponse<List<T>> queryList(String groqQuery, Map<String, Object> params, Class<T> elementType) throws SanityException {
TypeReference<QueryResponse<List<T>>> typeRef = new TypeReference<QueryResponse<List<T>>>() {};
return queryWithTypeReference(groqQuery, params, typeRef);
}
/**
* Execute query with TypeReference for complex types
*/
public <T> T queryWithTypeReference(String groqQuery, Map<String, Object> params, 
TypeReference<T> typeRef) throws SanityException {
try {
HttpUrl.Builder urlBuilder = HttpUrl.parse(baseUrl + "/data/query/" + dataset).newBuilder();
urlBuilder.addQueryParameter("query", groqQuery);
if (params != null && !params.isEmpty()) {
String paramsJson = objectMapper.writeValueAsString(params);
urlBuilder.addQueryParameter("$params", paramsJson);
}
Request request = createAuthenticatedRequest()
.url(urlBuilder.build())
.get()
.build();
try (Response response = httpClient.newCall(request).execute()) {
if (!response.isSuccessful()) {
throw new SanityException("Query failed: " + response.code() + " - " + response.message());
}
String responseBody = response.body().string();
return objectMapper.readValue(responseBody, typeRef);
}
} catch (IOException e) {
throw new SanityException("Query execution failed", e);
}
}
/**
* Create a new document
*/
public MutationResult create(Map<String, Object> document) throws SanityException {
List<Map<String, Object>> mutations = Collections.singletonList(
Collections.singletonMap("create", document)
);
return mutate(mutations);
}
/**
* Create a new document with specified type
*/
public <T> MutationResult create(T document) throws SanityException {
Map<String, Object> documentMap = objectMapper.convertValue(document, Map.class);
return create(documentMap);
}
/**
* Update an existing document
*/
public MutationResult update(String documentId, Map<String, Object> updates) throws SanityException {
List<Map<String, Object>> mutations = Collections.singletonList(
Collections.singletonMap("patch", 
Collections.singletonMap("id", documentId)
.with("set", updates)
)
);
return mutate(mutations);
}
/**
* Update an existing document with typed object
*/
public <T> MutationResult update(String documentId, T updates) throws SanityException {
Map<String, Object> updatesMap = objectMapper.convertValue(updates, Map.class);
return update(documentId, updatesMap);
}
/**
* Delete a document
*/
public MutationResult delete(String documentId) throws SanityException {
List<Map<String, Object>> mutations = Collections.singletonList(
Collections.singletonMap("delete", 
Collections.singletonMap("id", documentId)
)
);
return mutate(mutations);
}
/**
* Execute multiple mutations in a transaction
*/
public MutationResult mutate(List<Map<String, Object>> mutations) throws SanityException {
try {
String mutationsJson = objectMapper.writeValueAsString(mutations);
RequestBody body = RequestBody.create(
mutationsJson, 
MediaType.parse("application/json")
);
Request request = createAuthenticatedRequest()
.url(baseUrl + "/data/mutate/" + dataset)
.post(body)
.build();
try (Response response = httpClient.newCall(request).execute()) {
return parseMutationResponse(response);
}
} catch (IOException e) {
throw new SanityException("Mutation failed", e);
}
}
/**
* Upload file to Sanity
*/
public AssetUploadResult uploadAsset(byte[] fileData, String contentType, String originalFilename) throws SanityException {
try {
// Step 1: Begin upload
Map<String, String> beginUploadRequest = Collections.singletonMap(
"contentType", contentType
);
String beginUploadJson = objectMapper.writeValueAsString(beginUploadRequest);
Request beginRequest = createAuthenticatedRequest()
.url(baseUrl + "/assets/images/" + dataset)
.post(RequestBody.create(beginUploadJson, MediaType.parse("application/json")))
.build();
String uploadUrl;
String assetId;
try (Response beginResponse = httpClient.newCall(beginRequest).execute()) {
if (!beginResponse.isSuccessful()) {
throw new SanityException("Failed to begin upload: " + beginResponse.code());
}
String beginResponseBody = beginResponse.body().string();
Map<String, Object> beginResult = objectMapper.readValue(beginResponseBody, Map.class);
uploadUrl = (String) beginResult.get("url");
assetId = (String) beginResult.get("id");
}
// Step 2: Upload file data
Request uploadRequest = new Request.Builder()
.url(uploadUrl)
.put(RequestBody.create(fileData, MediaType.parse(contentType)))
.build();
try (Response uploadResponse = httpClient.newCall(uploadRequest).execute()) {
if (!uploadResponse.isSuccessful()) {
throw new SanityException("File upload failed: " + uploadResponse.code());
}
}
// Step 3: Commit upload
Map<String, Object> commitRequest = new HashMap<>();
commitRequest.put("id", assetId);
commitRequest.put("originalFilename", originalFilename);
String commitJson = objectMapper.writeValueAsString(commitRequest);
Request commitRequestObj = createAuthenticatedRequest()
.url(baseUrl + "/assets/images/" + dataset)
.post(RequestBody.create(commitJson, MediaType.parse("application/json")))
.build();
try (Response commitResponse = httpClient.newCall(commitRequestObj).execute()) {
if (!commitResponse.isSuccessful()) {
throw new SanityException("Upload commit failed: " + commitResponse.code());
}
String commitResponseBody = commitResponse.body().string();
return objectMapper.readValue(commitResponseBody, AssetUploadResult.class);
}
} catch (IOException e) {
throw new SanityException("Asset upload failed", e);
}
}
/**
* Get project information
*/
public ProjectInfo getProjectInfo() throws SanityException {
try {
Request request = createAuthenticatedRequest()
.url("https://" + projectId + ".api.sanity.io/v1/projects/" + projectId)
.get()
.build();
try (Response response = httpClient.newCall(request).execute()) {
if (!response.isSuccessful()) {
throw new SanityException("Failed to get project info: " + response.code());
}
String responseBody = response.body().string();
return objectMapper.readValue(responseBody, ProjectInfo.class);
}
} catch (IOException e) {
throw new SanityException("Failed to get project info", e);
}
}
// Helper methods
private Request.Builder createAuthenticatedRequest() {
Request.Builder builder = new Request.Builder()
.addHeader("Content-Type", "application/json");
if (token != null && !token.isEmpty()) {
builder.addHeader("Authorization", "Bearer " + token);
}
return builder;
}
private <T> QueryResponse<T> parseQueryResponse(Response response, Class<T> resultType) throws IOException {
if (!response.isSuccessful()) {
throw new SanityException("Query failed: " + response.code() + " - " + response.message());
}
String responseBody = response.body().string();
QueryResponse<Map<String, Object>> rawResponse = objectMapper.readValue(
responseBody, 
new TypeReference<QueryResponse<Map<String, Object>>>() {}
);
QueryResponse<T> typedResponse = new QueryResponse<>();
typedResponse.setMs(rawResponse.getMs());
typedResponse.setQuery(rawResponse.getQuery());
if (rawResponse.getResult() != null) {
T convertedResult = objectMapper.convertValue(rawResponse.getResult(), resultType);
typedResponse.setResult(convertedResult);
}
return typedResponse;
}
private MutationResult parseMutationResponse(Response response) throws IOException {
if (!response.isSuccessful()) {
throw new SanityException("Mutation failed: " + response.code() + " - " + response.message());
}
String responseBody = response.body().string();
return objectMapper.readValue(responseBody, MutationResult.class);
}
// Custom exception
public static class SanityException extends Exception {
public SanityException(String message) {
super(message);
}
public SanityException(String message, Throwable cause) {
super(message, cause);
}
}
}

Data Models

Response Data Classes

package com.sanity.model;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.List;
import java.util.Map;
// Query Response
@JsonIgnoreProperties(ignoreUnknown = true)
public class QueryResponse<T> {
private String query;
private long ms;
private T result;
// Getters and setters
public String getQuery() { return query; }
public void setQuery(String query) { this.query = query; }
public long getMs() { return ms; }
public void setMs(long ms) { this.ms = ms; }
public T getResult() { return result; }
public void setResult(T result) { this.result = result; }
}
// Mutation Result
@JsonIgnoreProperties(ignoreUnknown = true)
class MutationResult {
private String transactionId;
private List<MutationResultItem> results;
// Getters and setters
public String getTransactionId() { return transactionId; }
public void setTransactionId(String transactionId) { this.transactionId = transactionId; }
public List<MutationResultItem> getResults() { return results; }
public void setResults(List<MutationResultItem> results) { this.results = results; }
}
// Mutation Result Item
@JsonIgnoreProperties(ignoreUnknown = true)
class MutationResultItem {
private String id;
private String operation;
// Getters and setters
public String getId() { return id; }
public void setId(String id) { this.id = id; }
public String getOperation() { return operation; }
public void setOperation(String operation) { this.operation = operation; }
}
// Asset Upload Result
@JsonIgnoreProperties(ignoreUnknown = true)
class AssetUploadResult {
private String id;
private String url;
private String path;
private String originalFilename;
private long size;
private String mimeType;
// Getters and setters
public String getId() { return id; }
public void setId(String id) { this.id = id; }
public String getUrl() { return url; }
public void setUrl(String url) { this.url = url; }
public String getPath() { return path; }
public void setPath(String path) { this.path = path; }
public String getOriginalFilename() { return originalFilename; }
public void setOriginalFilename(String originalFilename) { this.originalFilename = originalFilename; }
public long getSize() { return size; }
public void setSize(long size) { this.size = size; }
public String getMimeType() { return mimeType; }
public void setMimeType(String mimeType) { this.mimeType = mimeType; }
}
// Project Information
@JsonIgnoreProperties(ignoreUnknown = true)
class ProjectInfo {
private String id;
private String displayName;
private String studioHost;
private String organizationId;
private boolean isBlocked;
private boolean isDisabled;
private boolean isDisabledByUser;
private String createdAt;
private String updatedAt;
private String membership;
// Getters and setters
public String getId() { return id; }
public void setId(String id) { this.id = id; }
public String getDisplayName() { return displayName; }
public void setDisplayName(String displayName) { this.displayName = displayName; }
public String getStudioHost() { return studioHost; }
public void setStudioHost(String studioHost) { this.studioHost = studioHost; }
public String getOrganizationId() { return organizationId; }
public void setOrganizationId(String organizationId) { this.organizationId = organizationId; }
public boolean isBlocked() { return isBlocked; }
public void setBlocked(boolean blocked) { isBlocked = blocked; }
public boolean isDisabled() { return isDisabled; }
public void setDisabled(boolean disabled) { isDisabled = disabled; }
public boolean isDisabledByUser() { return isDisabledByUser; }
public void setDisabledByUser(boolean disabledByUser) { isDisabledByUser = disabledByUser; }
public String getCreatedAt() { return createdAt; }
public void setCreatedAt(String createdAt) { this.createdAt = createdAt; }
public String getUpdatedAt() { return updatedAt; }
public void setUpdatedAt(String updatedAt) { this.updatedAt = updatedAt; }
public String getMembership() { return membership; }
public void setMembership(String membership) { this.membership = membership; }
}
// Sanity Document Base Class
@JsonIgnoreProperties(ignoreUnknown = true)
class SanityDocument {
@JsonProperty("_id")
private String id;
@JsonProperty("_type")
private String type;
@JsonProperty("_createdAt")
private String createdAt;
@JsonProperty("_updatedAt")
private String updatedAt;
@JsonProperty("_rev")
private String revision;
// Getters and setters
public String getId() { return id; }
public void setId(String id) { this.id = id; }
public String getType() { return type; }
public void setType(String type) { this.type = type; }
public String getCreatedAt() { return createdAt; }
public void setCreatedAt(String createdAt) { this.createdAt = createdAt; }
public String getUpdatedAt() { return updatedAt; }
public void setUpdatedAt(String updatedAt) { this.updatedAt = updatedAt; }
public String getRevision() { return revision; }
public void setRevision(String revision) { this.revision = revision; }
}
// Example Content Types
class Post extends SanityDocument {
private String title;
private String slug;
private String body;
private Author author;
private List<String> categories;
private SanityImage mainImage;
private String publishedAt;
// Getters and setters
public String getTitle() { return title; }
public void setTitle(String title) { this.title = title; }
public String getSlug() { return slug; }
public void setSlug(String slug) { this.slug = slug; }
public String getBody() { return body; }
public void setBody(String body) { this.body = body; }
public Author getAuthor() { return author; }
public void setAuthor(Author author) { this.author = author; }
public List<String> getCategories() { return categories; }
public void setCategories(List<String> categories) { this.categories = categories; }
public SanityImage getMainImage() { return mainImage; }
public void setMainImage(SanityImage mainImage) { this.mainImage = mainImage; }
public String getPublishedAt() { return publishedAt; }
public void setPublishedAt(String publishedAt) { this.publishedAt = publishedAt; }
}
class Author extends SanityDocument {
private String name;
private String bio;
private SanityImage image;
private String email;
// Getters and setters
public String getName() { return name; }
public void setName(String name) { this.name = name; }
public String getBio() { return bio; }
public void setBio(String bio) { this.bio = bio; }
public SanityImage getImage() { return image; }
public void setImage(SanityImage image) { this.image = image; }
public String getEmail() { return email; }
public void setEmail(String email) { this.email = email; }
}
class SanityImage {
@JsonProperty("_type")
private String type = "image";
private Asset asset;
// Getters and setters
public String getType() { return type; }
public void setType(String type) { this.type = type; }
public Asset getAsset() { return asset; }
public void setAsset(Asset asset) { this.asset = asset; }
// Helper method to generate image URL
public String getUrl() {
if (asset != null && asset.getRef() != null) {
return "https://cdn.sanity.io/images/" + 
extractProjectId(asset.getRef()) + "/" +
extractDataset(asset.getRef()) + "/" +
extractAssetId(asset.getRef());
}
return null;
}
public String getUrlWithOptions(int width, int height) {
String baseUrl = getUrl();
if (baseUrl != null) {
return baseUrl + "?w=" + width + "&h=" + height + "&fit=crop";
}
return null;
}
private String extractProjectId(String ref) {
// Implementation to extract project ID from asset reference
return ref.split("-")[0];
}
private String extractDataset(String ref) {
// Implementation to extract dataset from asset reference
return "production"; // Default dataset
}
private String extractAssetId(String ref) {
// Implementation to extract asset ID from asset reference
return ref;
}
}
class Asset {
@JsonProperty("_ref")
private String ref;
@JsonProperty("_type")
private String type = "reference";
// Getters and setters
public String getRef() { return ref; }
public void setRef(String ref) { this.ref = ref; }
public String getType() { return type; }
public void setType(String type) { this.type = type; }
}

Real-time Subscription Service

Live Query Subscriptions

package com.sanity.realtime;
import com.fasterxml.jackson.databind.ObjectMapper;
import okhttp3.*;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.io.IOException;
import java.util.*;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.CopyOnWriteArrayList;
import java.util.concurrent.atomic.AtomicInteger;
public class SanityRealtimeService {
private static final Logger logger = LoggerFactory.getLogger(SanityRealtimeService.class);
private final String projectId;
private final String dataset;
private final String token;
private final OkHttpClient httpClient;
private final ObjectMapper objectMapper;
private final Map<String, Subscription> subscriptions;
private final AtomicInteger listenerIdCounter;
public SanityRealtimeService(String projectId, String dataset, String token) {
this.projectId = projectId;
this.dataset = dataset;
this.token = token;
this.httpClient = new OkHttpClient();
this.objectMapper = new ObjectMapper();
this.subscriptions = new ConcurrentHashMap<>();
this.listenerIdCounter = new AtomicInteger(1);
}
/**
* Subscribe to real-time updates for a GROQ query
*/
public <T> String subscribe(String query, Map<String, Object> params, 
RealtimeListener<T> listener, Class<T> resultType) {
String subscriptionId = generateSubscriptionId();
Subscription subscription = new Subscription(
subscriptionId, query, params, listener, resultType
);
subscriptions.put(subscriptionId, subscription);
startSubscription(subscription);
return subscriptionId;
}
/**
* Unsubscribe from real-time updates
*/
public void unsubscribe(String subscriptionId) {
Subscription subscription = subscriptions.remove(subscriptionId);
if (subscription != null) {
subscription.close();
}
}
/**
* Start a subscription using Server-Sent Events (SSE)
*/
private <T> void startSubscription(Subscription<T> subscription) {
try {
String query = subscription.getQuery();
Map<String, Object> params = subscription.getParams();
// Build listen URL
HttpUrl.Builder urlBuilder = HttpUrl.parse(
"https://" + projectId + ".api.sanity.io/v1/data/listen/" + dataset
).newBuilder();
urlBuilder.addQueryParameter("query", query);
if (params != null && !params.isEmpty()) {
String paramsJson = objectMapper.writeValueAsString(params);
urlBuilder.addQueryParameter("$params", paramsJson);
}
Request request = new Request.Builder()
.url(urlBuilder.build())
.addHeader("Authorization", "Bearer " + token)
.addHeader("Accept", "text/event-stream")
.build();
RealTimeSSEListener sseListener = new RealTimeSSEListener<>(subscription);
subscription.setEventSource(new EventSource(request, sseListener));
} catch (Exception e) {
logger.error("Failed to start subscription: {}", e.getMessage(), e);
subscription.getListener().onError(e);
}
}
private String generateSubscriptionId() {
return "sub-" + System.currentTimeMillis() + "-" + listenerIdCounter.getAndIncrement();
}
// Subscription class
private static class Subscription<T> {
private final String id;
private final String query;
private final Map<String, Object> params;
private final RealtimeListener<T> listener;
private final Class<T> resultType;
private EventSource eventSource;
public Subscription(String id, String query, Map<String, Object> params, 
RealtimeListener<T> listener, Class<T> resultType) {
this.id = id;
this.query = query;
this.params = params;
this.listener = listener;
this.resultType = resultType;
}
public void close() {
if (eventSource != null) {
eventSource.cancel();
}
}
// Getters and setters
public String getId() { return id; }
public String getQuery() { return query; }
public Map<String, Object> getParams() { return params; }
public RealtimeListener<T> getListener() { return listener; }
public Class<T> getResultType() { return resultType; }
public EventSource getEventSource() { return eventSource; }
public void setEventSource(EventSource eventSource) { this.eventSource = eventSource; }
}
// SSE Listener for real-time updates
private class RealTimeSSEListener<T> extends EventSourceListener {
private final Subscription<T> subscription;
private final ObjectMapper objectMapper;
public RealTimeSSEListener(Subscription<T> subscription) {
this.subscription = subscription;
this.objectMapper = new ObjectMapper();
}
@Override
public void onOpen(EventSource eventSource, Response response) {
logger.info("Real-time connection opened for subscription: {}", subscription.getId());
subscription.getListener().onConnected();
}
@Override
public void onEvent(EventSource eventSource, String id, String type, String data) {
try {
if ("message".equals(type)) {
handleMessage(data);
}
} catch (Exception e) {
logger.error("Error processing real-time event: {}", e.getMessage(), e);
subscription.getListener().onError(e);
}
}
@Override
public void onClosed(EventSource eventSource) {
logger.info("Real-time connection closed for subscription: {}", subscription.getId());
subscription.getListener().onDisconnected();
}
@Override
public void onFailure(EventSource eventSource, Throwable t, Response response) {
logger.error("Real-time connection failed for subscription: {}", subscription.getId(), t);
subscription.getListener().onError(t);
}
private void handleMessage(String data) throws IOException {
Map<String, Object> message = objectMapper.readValue(data, Map.class);
String messageType = (String) message.get("type");
switch (messageType) {
case "welcome":
handleWelcome(message);
break;
case "mutation":
handleMutation(message);
break;
case "disconnect":
handleDisconnect(message);
break;
default:
logger.debug("Unknown message type: {}", messageType);
}
}
private void handleWelcome(Map<String, Object> message) {
logger.info("Received welcome message for subscription: {}", subscription.getId());
}
@SuppressWarnings("unchecked")
private void handleMutation(Map<String, Object> message) {
try {
Map<String, Object> result = (Map<String, Object>) message.get("result");
if (result != null) {
T typedResult = objectMapper.convertValue(result, subscription.getResultType());
subscription.getListener().onUpdate(typedResult);
}
} catch (Exception e) {
logger.error("Error processing mutation: {}", e.getMessage(), e);
}
}
private void handleDisconnect(Map<String, Object> message) {
String reason = (String) message.get("reason");
logger.warn("Disconnected from real-time updates: {}", reason);
}
}
// Custom EventSource implementation for SSE
private static class EventSource {
private final Request request;
private final EventSourceListener listener;
private okhttp3.EventSource okhttpEventSource;
public EventSource(Request request, EventSourceListener listener) {
this.request = request;
this.listener = listener;
}
public void start(OkHttpClient client) {
okhttp3.EventSource.Factory factory = okhttp3.EventSource.Factory.create(client);
okhttpEventSource = factory.newEventSource(request, new okhttp3.EventSourceListener() {
@Override
public void onOpen(okhttp3.EventSource eventSource, Response response) {
listener.onOpen(EventSource.this, response);
}
@Override
public void onEvent(okhttp3.EventSource eventSource, String id, String type, String data) {
listener.onEvent(EventSource.this, id, type, data);
}
@Override
public void onClosed(okhttp3.EventSource eventSource) {
listener.onClosed(EventSource.this);
}
@Override
public void onFailure(okhttp3.EventSource eventSource, Throwable t, Response response) {
listener.onFailure(EventSource.this, t, response);
}
});
}
public void cancel() {
if (okhttpEventSource != null) {
okhttpEventSource.cancel();
}
}
}
// Event Source Listener interface
private abstract static class EventSourceListener {
public void onOpen(EventSource eventSource, Response response) {}
public void onEvent(EventSource eventSource, String id, String type, String data) {}
public void onClosed(EventSource eventSource) {}
public void onFailure(EventSource eventSource, Throwable t, Response response) {}
}
}
// Real-time Listener Interface
interface RealtimeListener<T> {
void onConnected();
void onDisconnected();
void onUpdate(T data);
void onError(Throwable error);
}

Advanced Query Builder

GROQ Query Builder

package com.sanity.query;
import java.util.*;
import java.util.stream.Collectors;
public class GroqQueryBuilder {
private final StringBuilder query;
private final Map<String, Object> parameters;
private final Set<String> projections;
private final List<String> filters;
private final List<String> orders;
private Integer limit;
private Integer offset;
public GroqQueryBuilder() {
this.query = new StringBuilder();
this.parameters = new HashMap<>();
this.projections = new LinkedHashSet<>();
this.filters = new ArrayList<>();
this.orders = new ArrayList<>();
}
/**
* Start building a query for a specific document type
*/
public static GroqQueryBuilder forType(String documentType) {
GroqQueryBuilder builder = new GroqQueryBuilder();
builder.query.append("*[_type == \"").append(documentType).append("\"]");
return builder;
}
/**
* Start building a query with custom base
*/
public static GroqQueryBuilder from(String baseQuery) {
GroqQueryBuilder builder = new GroqQueryBuilder();
builder.query.append(baseQuery);
return builder;
}
/**
* Add field projection
*/
public GroqQueryBuilder project(String field) {
projections.add(field);
return this;
}
/**
* Add multiple field projections
*/
public GroqQueryBuilder project(String... fields) {
projections.addAll(Arrays.asList(fields));
return this;
}
/**
* Add field projection with alias
*/
public GroqQueryBuilder project(String field, String alias) {
projections.add(alias + ": " + field);
return this;
}
/**
* Add filter condition
*/
public GroqQueryBuilder filter(String condition) {
filters.add(condition);
return this;
}
/**
* Add equality filter
*/
public GroqQueryBuilder whereEquals(String field, Object value) {
String paramName = addParameter(value);
filters.add(field + " == $" + paramName);
return this;
}
/**
* Add inequality filter
*/
public GroqQueryBuilder whereNotEquals(String field, Object value) {
String paramName = addParameter(value);
filters.add(field + " != $" + paramName);
return this;
}
/**
* Add range filter (greater than)
*/
public GroqQueryBuilder whereGreaterThan(String field, Object value) {
String paramName = addParameter(value);
filters.add(field + " > $" + paramName);
return this;
}
/**
* Add range filter (less than)
*/
public GroqQueryBuilder whereLessThan(String field, Object value) {
String paramName = addParameter(value);
filters.add(field + " < $" + paramName);
return this;
}
/**
* Add contains filter for arrays
*/
public GroqQueryBuilder whereContains(String field, Object value) {
String paramName = addParameter(value);
filters.add("$" + paramName + " in " + field);
return this;
}
/**
* Add ordering
*/
public GroqQueryBuilder orderBy(String field, OrderDirection direction) {
orders.add(field + " " + direction.name().toLowerCase());
return this;
}
/**
* Add ordering with nulls first/last
*/
public GroqQueryBuilder orderBy(String field, OrderDirection direction, NullsOrder nullsOrder) {
orders.add(field + " " + direction.name().toLowerCase() + " " + nullsOrder.name().replace('_', ' ').toLowerCase());
return this;
}
/**
* Set result limit
*/
public GroqQueryBuilder limit(int limit) {
this.limit = limit;
return this;
}
/**
* Set result offset
*/
public GroqQueryBuilder offset(int offset) {
this.offset = offset;
return this;
}
/**
* Build the final GROQ query string
*/
public String build() {
StringBuilder finalQuery = new StringBuilder(query);
// Add filters
if (!filters.isEmpty()) {
finalQuery.append("[").append(String.join(" && ", filters)).append("]");
}
// Add projections
if (!projections.isEmpty()) {
finalQuery.append("{").append(String.join(", ", projections)).append("}");
}
// Add ordering
if (!orders.isEmpty()) {
finalQuery.append(" | order(").append(String.join(", ", orders)).append(")");
}
// Add limit
if (limit != null) {
finalQuery.append("[0...").append(limit).append("]");
}
// Add offset
if (offset != null) {
if (limit == null) {
finalQuery.append("[").append(offset).append("]");
} else {
// If both limit and offset are specified, use range syntax
finalQuery.setLength(finalQuery.length() - (String.valueOf(limit).length() + 4));
finalQuery.append("[").append(offset).append("...").append(offset + limit).append("]");
}
}
return finalQuery.toString();
}
/**
* Get query parameters
*/
public Map<String, Object> getParameters() {
return Collections.unmodifiableMap(parameters);
}
/**
* Add parameter and return parameter name
*/
private String addParameter(Object value) {
String paramName = "param" + (parameters.size() + 1);
parameters.put(paramName, value);
return paramName;
}
public enum OrderDirection {
ASC, DESC
}
public enum NullsOrder {
NULLS_FIRST, NULLS_LAST
}
}

Spring Boot Integration

Configuration Class

package com.sanity.config;
import com.sanity.client.SanityClient;
import com.sanity.realtime.SanityRealtimeService;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class SanityConfig {
@Value("${sanity.project.id}")
private String projectId;
@Value("${sanity.dataset:production}")
private String dataset;
@Value("${sanity.token:}")
private String token;
@Value("${sanity.use-cdn:true}")
private boolean useCdn;
@Bean
public SanityClient sanityClient() {
return new SanityClient(projectId, dataset, token, useCdn);
}
@Bean
public SanityRealtimeService sanityRealtimeService() {
return new SanityRealtimeService(projectId, dataset, token);
}
}

REST Controller

package com.sanity.controller;
import com.sanity.client.SanityClient;
import com.sanity.model.Post;
import com.sanity.query.GroqQueryBuilder;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
@RestController
@RequestMapping("/api/content")
public class ContentController {
@Autowired
private SanityClient sanityClient;
@GetMapping("/posts")
public ResponseEntity<Map<String, Object>> getAllPosts(
@RequestParam(defaultValue = "10") int limit,
@RequestParam(defaultValue = "0") int offset) {
Map<String, Object> response = new HashMap<>();
try {
// Build query using GroqQueryBuilder
String query = GroqQueryBuilder.forType("post")
.project("_id", "title", "slug", "body", "publishedAt", "mainImage")
.orderBy("publishedAt", GroqQueryBuilder.OrderDirection.DESC)
.limit(limit)
.offset(offset)
.build();
var result = sanityClient.queryList(query, Post.class);
response.put("success", true);
response.put("posts", result.getResult());
response.put("total", result.getResult().size());
response.put("queryTime", result.getMs());
return ResponseEntity.ok(response);
} catch (Exception e) {
response.put("success", false);
response.put("error", e.getMessage());
return ResponseEntity.badRequest().body(response);
}
}
@GetMapping("/posts/{slug}")
public ResponseEntity<Map<String, Object>> getPostBySlug(@PathVariable String slug) {
Map<String, Object> response = new HashMap<>();
try {
String query = GroqQueryBuilder.forType("post")
.project("_id", "title", "slug", "body", "publishedAt", "mainImage", "author")
.whereEquals("slug.current", slug)
.limit(1)
.build();
var result = sanityClient.queryList(query, Post.class);
if (result.getResult().isEmpty()) {
response.put("success", false);
response.put("error", "Post not found");
return ResponseEntity.notFound().build();
}
response.put("success", true);
response.put("post", result.getResult().get(0));
return ResponseEntity.ok(response);
} catch (Exception e) {
response.put("success", false);
response.put("error", e.getMessage());
return ResponseEntity.badRequest().body(response);
}
}
@GetMapping("/posts/search")
public ResponseEntity<Map<String, Object>> searchPosts(@RequestParam String query) {
Map<String, Object> response = new HashMap<>();
try {
String groqQuery = GroqQueryBuilder.forType("post")
.project("_id", "title", "slug", "body", "publishedAt")
.filter("title match $searchQuery || body match $searchQuery")
.orderBy("publishedAt", GroqQueryBuilder.OrderDirection.DESC)
.limit(20)
.build();
Map<String, Object> params = new HashMap<>();
params.put("searchQuery", query + "*");
var result = sanityClient.queryList(groqQuery, params, Post.class);
response.put("success", true);
response.put("posts", result.getResult());
response.put("count", result.getResult().size());
return ResponseEntity.ok(response);
} catch (Exception e) {
response.put("success", false);
response.put("error", e.getMessage());
return ResponseEntity.badRequest().body(response);
}
}
@PostMapping("/posts")
public ResponseEntity<Map<String, Object>> createPost(@RequestBody Post post) {
Map<String, Object> response = new HashMap<>();
try {
var result = sanityClient.create(post);
response.put("success", true);
response.put("documentId", result.getResults().get(0).getId());
response.put("transactionId", result.getTransactionId());
return ResponseEntity.ok(response);
} catch (Exception e) {
response.put("success", false);
response.put("error", e.getMessage());
return ResponseEntity.badRequest().body(response);
}
}
}

Application Properties

# Sanity.io Configuration
sanity.project.id=your-project-id
sanity.dataset=production
sanity.token=your-sanit-token
sanity.use-cdn=true
# Server Configuration
server.port=8080
# Logging
logging.level.com.sanity=INFO

Usage Examples

Basic Usage

package com.sanity.examples;
import com.sanity.client.SanityClient;
import com.sanity.model.Post;
import com.sanity.query.GroqQueryBuilder;
import java.util.List;
import java.util.Map;
public class SanityExamples {
public static void main(String[] args) {
// Initialize client
SanityClient client = new SanityClient(
"your-project-id", 
"production", 
"your-token"
);
try {
// Example 1: Query all posts
String query = GroqQueryBuilder.forType("post")
.project("_id", "title", "slug", "publishedAt")
.orderBy("publishedAt", GroqQueryBuilder.OrderDirection.DESC)
.limit(10)
.build();
var result = client.queryList(query, Post.class);
List<Post> posts = result.getResult();
// Example 2: Query with parameters
String paramQuery = GroqQueryBuilder.forType("post")
.project("title", "slug")
.whereEquals("publishedAt", "2023-01-01")
.build();
Map<String, Object> params = Map.of("publishedAt", "2023-01-01");
var paramResult = client.queryList(paramQuery, params, Post.class);
// Example 3: Create a new post
Post newPost = new Post();
newPost.setTitle("New Blog Post");
newPost.setSlug("new-blog-post");
newPost.setBody("This is the content of the new blog post.");
var createResult = client.create(newPost);
System.out.println("Created post with ID: " + createResult.getResults().get(0).getId());
} catch (Exception e) {
e.printStackTrace();
}
}
}

Conclusion

This comprehensive Sanity.io Java client provides:

  1. Complete API coverage for queries, mutations, and assets
  2. Real-time subscriptions for live content updates
  3. Type-safe models for Java integration
  4. Query builder for constructing GROQ queries
  5. Spring Boot integration for easy configuration
  6. Error handling and comprehensive logging

Key features:

  • GROQ query execution with parameter support
  • Document mutations for create, update, and delete operations
  • Asset management for file uploads
  • Real-time updates using Server-Sent Events
  • Type-safe response parsing with Jackson
  • Flexible query building with the GroqQueryBuilder

This implementation enables Java applications to seamlessly integrate with Sanity.io headless CMS, providing robust content management capabilities with real-time updates and type safety.

Category : JAVA

Leave a Reply

Your email address will not be published. Required fields are marked *


Macro Nepal Helper