OddSockets Java SDK

Official Java SDK for OddSockets real-time messaging platform.

Features

• Enterprise Ready: Built for production with comprehensive error handling
• Spring Boot Friendly: Drop the client into any Spring service as a bean
• Enhanced Surface: Slack-like reactions, threads, typing, presence and more
• Low Latency: Real-time delivery with automatic reconnection
• Cost Effective: No per-message pricing, no message size limits
• Cloud Native: Perfect for microservices and enterprise applications

📦 Installation

Maven

<dependency>
    <groupId>com.oddsockets</groupId>
    <artifactId>oddsockets-java-sdk</artifactId>
    <version>0.1.0-beta.1</version>
</dependency>

Gradle

implementation 'com.oddsockets:oddsockets-java-sdk:0.1.0-beta.1'

🏃‍♂️ Quick Start

Basic Usage

import com.oddsockets.OddSockets;
import com.oddsockets.Channel;
import com.oddsockets.Message;
import com.oddsockets.config.OddSocketsConfig;

public class BasicExample {
    public static void main(String[] args) {
        // Create client
        OddSocketsConfig config = OddSocketsConfig.builder()
            .apiKey("ak_live_1234567890abcdef")
            .managerUrl("https://connect.oddsockets.tyga.network")
            .userId("java-demo-user")
            .build();

        OddSockets client = new OddSockets(config);

        try {
            // Connect to OddSockets
            client.connect().get();

            // Create channel
            Channel channel = client.channel("my-channel");

            // Subscribe to messages
            channel.subscribe(message -> {
                System.out.println("Received: " + message.getData());
            }, SubscribeOptions.builder()
                .enablePresence(true)
                .retainHistory(true)
                .build()).get();

            // Publish a message
            channel.publish("Hello from Java! ☕", PublishOptions.builder()
                .metadata(Map.of("source", "java-sdk"))
                .storeInHistory(true)
                .build()).get();

            // Keep alive
            Thread.sleep(5000);

        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            client.disconnect();
        }
    }
}

Spring Boot Integration

@RestController
@RequiredArgsConstructor
public class MessageController {
    
    private final OddSockets oddSockets;
    
    @PostMapping("/send-message")
    public CompletableFuture<PublishResult> sendMessage(@RequestBody MessageRequest request) {
        Channel channel = oddSockets.channel(request.getChannel());
        
        return channel.publish(request.getMessage(), PublishOptions.builder()
            .metadata(Map.of("timestamp", Instant.now().toString()))
            .storeInHistory(true)
            .build());
    }
    
    @GetMapping("/channel/{name}/presence")
    public CompletableFuture<PresenceInfo> getPresence(@PathVariable String name) {
        return oddSockets.channel(name).getPresence();
    }
}

Enhanced Features

Beyond core pub/sub, OddSockets ships a Slack-like enhanced surface — reactions, typing indicators, threads, read receipts, presence/status, notifications, DMs, channel management, message editing and search. It lives on client.enhanced. The pattern is always the same:

1. Send an action with a client.enhanced.* method (camelCase).
2. Receive the paired broadcast with client.on("<event>", handler).

import com.google.gson.JsonObject;
import com.oddsockets.OddSockets;
import com.oddsockets.config.OddSocketsConfig;

OddSockets client = new OddSockets(OddSocketsConfig.builder()
    .apiKey("ak_live_1234567890abcdef")
    .userId("alice")
    .build());
client.connect().get();

// Receive-path: broadcasts from other users on the channel
client.on("user_typing",    data -> System.out.println("user is typing"));
client.on("reaction_added", data -> System.out.println("reaction added"));
client.on("thread_reply",   data -> System.out.println("new thread reply"));

// Send-path: enhanced actions over the live socket
client.enhanced.startTyping("alice", "room-42");
client.enhanced.addReaction("msg-1", "room-42", ":thumbsup:", "alice", "Alice");
client.enhanced.threadReply("room-42", "msg-1", "Replying in the thread", "alice", "Alice");

Each area exposes methods on client.enhanced; the worker broadcasts the paired events which you handle with client.on(...). Query methods (get*, search*) return a CompletableFuture<JsonObject> that completes with the worker response.

Area	Requests (client.enhanced.*)	Broadcast events (client.on)
Typing	startTyping, stopTyping	user_typing, user_stopped_typing
Reactions	addReaction, removeReaction, getReactions	reaction_added, reaction_removed
Threads	threadReply, getThread, subscribeThread, followThread, markThreadRead	thread_reply, thread_subscribed, thread_followed, thread_read_updated
Read receipts	markRead, markAllRead, getUnreadCounts	user_read, unread_count_updated, all_marked_read
Messages	editMessage, deleteMessage, pinMessage, unpinMessage, getPinnedMessages, searchMessages	message_edited, message_deleted, message_pinned, message_unpinned
Presence & status	setStatus, setCustomStatus, setDND, getUserPresence	user_status_changed, custom_status_updated, dnd_status_changed
Channels	createChannel, updateChannel, archiveChannel, inviteToChannel, joinChannel, leaveChannel	channel_created, channel_updated, user_invited, user_joined_channel, user_left_channel
DMs	createDM, sendDM, getDMConversations	dm_created, dm_received
Notifications	subscribeNotifications, getNotifications, markNotificationRead, clearNotifications	notification, notification_read, notifications_cleared
Search	searchMessages, searchInChannel, searchByUser, filterMessages	(future results)

For any worker event not wrapped above, subscribe with the raw client.on("<event>", handler) API — all enhanced broadcasts are forwarded onto the client surface.

Documentation

• SDK Documentation - Guides and API overview
• Javadoc - Full API reference

Examples

Explore the runnable examples:

• Basic Usage - Simple messaging
• Enhanced Features - Reactions, threads, typing and more
• Two-client demo - End-to-end enhanced broadcast regression

Configuration

Client Options

OddSocketsConfig config = OddSocketsConfig.builder()
    .apiKey("your-api-key")                    // Required: Your OddSockets API key
    .managerUrl("manager-url")                 // Optional: Manager URL
    .userId("user-id")                         // Optional: User identifier
    .autoConnect(true)                         // Optional: Auto-connect on creation
    .reconnectAttempts(5)                      // Optional: Max reconnection attempts
    .heartbeatInterval(Duration.ofSeconds(30)) // Optional: Heartbeat interval
    .requestTimeout(Duration.ofSeconds(10))    // Optional: Request timeout
    .build();

Manager URL

The manager URL is resolved in this order:

1. managerUrl(...) on the builder
2. the ODDSOCKETS_MANAGER_URL environment variable
3. https://connect.oddsockets.tyga.network

It must be an absolute http:// or https:// URL, otherwise the build fails with Invalid managerUrl: <value>. Point it at a self-hosted or staging manager and the SDK will use that endpoint and nothing else: if it is unreachable the connection fails with the underlying error rather than falling back to the public endpoint.

Channel Options

// Subscribe with options
channel.subscribe(messageHandler, SubscribeOptions.builder()
    .enablePresence(true)                      // Enable presence tracking
    .retainHistory(true)                       // Retain message history
    .filterExpression("user.premium == true")  // Message filter expression
    .build());

// Publish with options
channel.publish(message, PublishOptions.builder()
    .ttl(3600)                                 // Time to live (seconds)
    .metadata(Map.of("priority", "high"))      // Additional metadata
    .storeInHistory(true)                      // Store in message history
    .build());

Java Support

• Java 11+
• Spring Boot 2.7+ / 3.x
• Jakarta EE 9+

Testing

# Run tests
./mvnw test

# Run tests with coverage
./mvnw test jacoco:report

# Run integration tests
./mvnw test -Dtest.profile=integration

# Run performance tests
./mvnw test -Dtest.profile=performance

Building

# Build
./mvnw clean compile

# Package
./mvnw clean package

# Install to local repository
./mvnw clean install

# Deploy to Maven Central
./mvnw clean deploy -P release

Performance

OddSockets Java SDK delivers superior performance:

• Low latency real-time delivery
• 99.9% uptime with automatic failover
• Unlimited message size - no artificial limits
• High throughput - handle millions of messages with async pipelines

Security

• End-to-end encryption available
• API key authentication with fine-grained permissions
• Rate limiting and abuse protection
• GDPR compliant data handling

Framework Integrations

Spring Boot Auto-Configuration

# application.yml
oddsockets:
  api-key: ak_live_1234567890abcdef
  manager-url: https://connect.oddsockets.tyga.network
  user-id: spring-boot-user
  auto-connect: true
  reconnect-attempts: 5
  heartbeat-interval: 30s

@Component
@RequiredArgsConstructor
public class MessageService {
    
    private final OddSockets oddSockets;
    
    @EventListener
    public void handleApplicationReady(ApplicationReadyEvent event) {
        Channel channel = oddSockets.channel("system-events");
        
        channel.subscribe(message -> {
            // Handle system messages
            log.info("System message: {}", message.getData());
        });
    }
}

Microservices Architecture

@RestController
@RequestMapping("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/api/messages")
@RequiredArgsConstructor
public class MessageController {
    
    private final OddSockets oddSockets;
    
    @PostMapping("/broadcast")
    public CompletableFuture<List<PublishResult>> broadcast(@RequestBody BroadcastRequest request) {
        List<CompletableFuture<PublishResult>> futures = request.getChannels().stream()
            .map(channelName -> oddSockets.channel(channelName)
                .publish(request.getMessage(), PublishOptions.builder()
                    .metadata(Map.of("broadcast_id", request.getBroadcastId()))
                    .storeInHistory(true)
                    .build()))
            .collect(Collectors.toList());
        
        return CompletableFuture.allOf(futures.toArray(new CompletableFuture[0]))
            .thenApply(v -> futures.stream()
                .map(CompletableFuture::join)
                .collect(Collectors.toList()));
    }
}

Other SDKs

OddSockets is available in multiple languages:

• JavaScript SDK - Browser + Node.js, TypeScript ready
• Python SDK - AsyncIO support, Django/Flask integrations
• Go SDK - High performance, goroutines and channels
• C# SDK - .NET Core/Framework, Azure integrations
• Swift SDK - iOS native, Combine framework
• Kotlin SDK - Android native, coroutines support

Get a Free API Key

AI agents can sign up with a verified email in two steps — no dashboard, no human required.

Step 1: Request a verification code

curl -X POST https://oddsockets.com/api/agent-signup \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "agentName": "my-agent", "platform": "java"}'

Step 2: Verify the 6-digit code from your email and get your API key

curl -X POST https://oddsockets.com/api/agent-signup/verify \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "code": "123456", "agentName": "my-agent"}'

Plans

	Free	Starter	Pro
Price	$0/mo	$49.99/mo	$299/mo
MAU	100	1,000	50,000
Concurrent connections	50	1,000	Unlimited
Messages/day	10,000	4,320,000	Unlimited
Messages/minute	100	3,000	Unlimited
Channels	10	Unlimited	Unlimited
Storage	100MB (24h)	50GB (6 months)	Unlimited

All limits are enforced in real time.

Get Accredited

Prove you can build and operate real-time features on OddSockets — channels, presence, pub/sub, delivery guarantees and production liveops — on the stack itself. Three tiers (TCU / TCA / TCP), certified through tyga.games and delivered on ClassaaS.

Get accredited on tyga.games →

Support

• Documentation
• Issue Tracker
• Email Support

License

MIT License - Copyright (c) 2026 Joe Wee, Tyga.Cloud Ltd. See LICENSE for details.