Skip to content

README.md

Latest commit

 

History

History
246 lines (185 loc) · 6.41 KB

README.md

File metadata and controls

246 lines (185 loc) · 6.41 KB

Orisun Java Client

A Java client for the Orisun event store, providing a simple and intuitive interface for interacting with the Orisun gRPC service.

Features

  • gRPC-based: Built on gRPC for high-performance communication
  • Type-safe: Generated from Protocol Buffer definitions
  • Easy to use: Simple builder pattern for client configuration
  • Authentication: Support for basic authentication with token caching
  • Dual Clients: Includes both OrisunClient (event operations) and AdminClient (user management)
  • Load Balancing: Support for single-server, multi-server, DNS-based, and static load balancing

Installation

Option 1: GitHub Packages (Recommended)

The client is published to GitHub Packages. To use it, you'll need to authenticate with your GitHub credentials.

Maven

Add the GitHub Packages repository and dependency to your pom.xml:

<repositories>
    <repository>
        <id>github</id>
        <url>https://maven.pkg.github.com/oexza/orisun-client-java</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.orisunlabs</groupId>
        <artifactId>orisun-java-client</artifactId>
        <version>0.0.1</version>
    </dependency>
</dependencies>

Configure authentication in your ~/.m2/settings.xml:

<server>
    <id>github</id>
    <username>YOUR_GITHUB_USERNAME</username>
    <password>YOUR_GITHUB_TOKEN</password>
</server>

Gradle

Add to your build.gradle:

repositories {
    maven {
        url = 'https://maven.pkg.github.com/oexza/orisun-client-java'
        credentials {
            username = project.findProperty('githubUsername') ?: System.getenv('GITHUB_USERNAME')
            password = project.findProperty('githubToken') ?: System.getenv('GITHUB_TOKEN')
        }
    }
}

dependencies {
    implementation 'com.orisunlabs:orisun-java-client:0.0.1'
}

Add credentials to ~/.gradle/gradle.properties:

githubUsername=YOUR_GITHUB_USERNAME
githubToken=YOUR_GITHUB_TOKEN

Note: You can create a GitHub personal access token at https://github.com/settings/tokens

Option 2: Download from GitHub Releases

If you prefer not to use GitHub Packages, you can download the JAR directly from Releases.

Download the orisun-java-client-{version}.jar file and use one of the methods below.

Maven - System Dependency

Place the JAR in your project's lib/ directory and add to pom.xml:

<dependency>
    <groupId>com.orisunlabs</groupId>
    <artifactId>orisun-java-client</artifactId>
    <version>0.0.1</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/lib/orisun-java-client-0.0.1.jar</systemPath>
</dependency>

Gradle - File Dependency

Place the JAR in your project's libs/ directory and add to build.gradle:

dependencies {
    implementation files('libs/orisun-java-client-0.0.1.jar')
}

Or use a flat directory repository:

repositories {
    flatDir { dirs 'libs' }
}

dependencies {
    implementation 'com.orisunlabs:orisun-java-client:0.0.1'
}

Building from Source

# Clone the repository
git clone https://github.com/oexza/orisun-client-java.git
cd orisun-client-java

# Initialize submodules
git submodule update --init --recursive

# Build with Gradle
./gradlew build

# The fat JAR with dependencies will be at: build/libs/orisun-client-{version}.jar

Proto Files

This client uses proto definitions from a submodule. To update the proto files:

# Update the submodule
git submodule update --remote protos

# Rebuild the project
./gradlew build

Quick Start

OrisunClient - Event Store Operations

import com.orisunlabs.orisun.client.OrisunClient;
import com.orisun.eventstore.Eventstore;
import java.util.UUID;

// Create a client
try (OrisunClient client = OrisunClient.newBuilder()
    .withServer("localhost", 5005)
    .withBasicAuth("admin", "changeit")
    .build()) {

    // Save events
    Eventstore.SaveEventsRequest request = Eventstore.SaveEventsRequest.newBuilder()
        .setBoundary("users")
        .addEvents(Eventstore.EventToSave.newBuilder()
            .setEventId(UUID.randomUUID().toString())
            .setEventType("UserCreated")
            .setData("{\"userId\":\"user-123\",\"email\":\"john@example.com\"}")
            .build())
        .build();

    Eventstore.WriteResult result = client.saveEvents(request);

    // Read events
    Eventstore.GetEventsResponse response = client.getEvents(
        Eventstore.GetEventsRequest.newBuilder()
            .setBoundary("users")
            .setCount(10)
            .build()
    );
}

AdminClient - User Management

import com.orisunlabs.orisun.client.AdminClient;
import com.orisun.admin.AdminOuterClass.*;

// Create an admin client
try (AdminClient adminClient = AdminClient.newBuilder()
    .withServer("localhost", 5005)
    .withBasicAuth("admin", "changeit")
    .build()) {

    // Create a user
    CreateUserRequest createRequest = CreateUserRequest.newBuilder()
        .setName("John Doe")
        .setUsername("johndoe")
        .setPassword("securePassword123")
        .addRoles("user")
        .build();

    AdminUser user = adminClient.createUser(createRequest);

    // List all users
    List<AdminUser> users = adminClient.listUsers();

    // Validate credentials
    ValidateCredentialsResponse response = adminClient.validateCredentials(
        ValidateCredentialsRequest.newBuilder()
            .setUsername("johndoe")
            .setPassword("securePassword123")
            .build()
    );
}

Advanced Configuration

Both clients support advanced configuration:

OrisunClient client = OrisunClient.newBuilder()
    .withServer("localhost", 5005)
    .withBasicAuth("admin", "changeit")
    .withTimeout(30)                              // Request timeout in seconds
    .withTls(false)                               // Use TLS
    .withLoadBalancingPolicy("round_robin")      // Load balancing policy
    .withKeepAliveTime(30000)                     // Keep-alive time in ms
    .withKeepAliveTimeout(10000)                  // Keep-alive timeout in ms
    .withLogging(true)                            // Enable logging
    .withLogLevel(com.orisunlabs.orisun.client.DefaultLogger.LogLevel.INFO)
    .build();

License

MIT License - see LICENSE for details.

Repository

https://github.com/oexza/orisun-client-java