Kessel SDK for Java

A Java SDK for connecting to Kessel services using gRPC with a fluent client builder API.

Table of Contents

• Installation
• Examples
• Development

Installation

Add to your Maven pom.xml:

<dependency>
    <groupId>org.project-kessel</groupId>
    <artifactId>kessel-sdk</artifactId>
    <version>1.2.1</version>
</dependency>

Authentication

The SDK supports OAuth 2.0 Client Credentials flow for authentication with automatic token caching and refresh.

Examples

Check out the examples directory for working code samples:

• Auth examples: OAuth2 Client Credentials flow with token management
• Builder examples: Fluent client builder patterns
• gRPC examples: Direct gRPC client usage

Run examples:

./mvnw clean install
cd examples
../mvnw compile exec:java -Prun-auth

Development

Building

./mvnw clean compile

Testing

./mvnw test

Installing

./mvnw clean install

Prerequisites

• Java 21 or higher
• Maven 3.6 or higher
• buf for protobuf/gRPC code generation (if contributing)

Release Instructions

This section provides step-by-step instructions for maintainers to release a new version of the Kessel SDK for Java.

Version Management

This project follows Semantic Versioning 2.0.0. Version numbers use the format MAJOR.MINOR.PATCH:

• MAJOR: Increment for incompatible API changes
• MINOR: Increment for backward-compatible functionality additions
• PATCH: Increment for backward-compatible bug fixes

Note: SDK versions across different languages (Ruby, Python, Go, etc.) do not need to be synchronized. Each language SDK can evolve independently based on its specific requirements and release schedule.

Prerequisites for Release

• Write access to the GitHub repository
• Maven central account with publish access to the org.project-kessel namespace
• Credentials configured for maven central
• GPG key for publishing to maven central
• Ensure quality checks are passing
• Review and update CHANGELOG or release notes as needed
• Java 21 or higher
• buf for protobuf/gRPC code generation:

  # On macOS
  brew install bufbuild/buf/buf
  
  # On Linux
  curl -sSL "https://github.com/bufbuild/buf/releases/latest/download/buf-$(uname -s)-$(uname -m)" -o "/usr/local/bin/buf" && chmod +x "/usr/local/bin/buf"

Release Process

1. Update the Version

# Update the project version across all modules
./mvnw versions:set -DnewVersion=X.Y.Z

# Ensure the root pom.xml now contains <version>X.Y.Z</version>

2. Update Dependencies (if needed)

# Regenerate gRPC code if there are updates to the Kessel Inventory API
buf generate

3. Run Quality Checks

# Build the project
./mvnw clean install
# Test that examples can compile without errors
cd examples
../mvnw compile exec:java -Prun-auth

4. Build and Publish the Package

It's required to configure your settings.xml with token credentials before deploying. You can follow the instructions found here for generating a user token and configuring your setings.xml.

For publishing it is also required to have a GPG key configured.

# Push deployment to maven central
./mvnw -B clean deploy -Psign

Check deployment page for errors before publishing on maven web portal. Verify that both org.project-kessel:kessel-sdk-parent and org.project-kessel:kessel-sdk are present in the staging repository before closing it.

5. Commit and Push Changes

# Revert changes to pom.xml
git stash
# Commit any related changes (if any, e.g. proto updates)
git commit -m "chore: bump version to X.Y.Z"
git push origin main # or git push upstream main

6. Tag the Release

# Create and push a git tag
git tag -a vX.Y.Z -m "Release version X.Y.Z"
git push origin vX.Y.Z

7. Create GitHub Release

• Go to the GitHub Releases page
• Click "Create a new release"
• Select the tag you just created
• Add release notes describing the changes
• Publish the release

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.