gitea/sdk/java

Gitea Java SDK

Official Java SDK for the Gitea API with chunked upload support for large files.

Requirements

• Java 17 or later
• Maven or Gradle

Installation

Maven

<dependency>
    <groupId>io.gitea</groupId>
    <artifactId>gitea-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle

implementation 'io.gitea:gitea-sdk:1.0.0'

Quick Start

import io.gitea.sdk.GiteaClient;
import io.gitea.sdk.models.*;

// Create client
var client = new GiteaClient("https://gitea.example.com", "your_token");

// Get current user
var user = client.getCurrentUser();
System.out.println("Logged in as " + user.getLogin());

// Get a repository
var repo = client.getRepository("owner", "repo");
System.out.println("Repository: " + repo.getFullName());

Chunked Upload

Upload large files with progress tracking:

import io.gitea.sdk.GiteaClient;
import io.gitea.sdk.models.*;

import java.io.FileInputStream;

var client = new GiteaClient("https://gitea.example.com", "your_token");

// Upload a release asset with progress
try (var fileStream = new FileInputStream("large-file.tar.gz")) {
    var fileSize = new java.io.File("large-file.tar.gz").length();

    var result = client.uploadReleaseAsset(
        "myorg",
        "myrepo",
        123L,
        fileStream,
        "large-file.tar.gz",
        fileSize,
        new ChunkedUploadOptions()
            .setChunkSize(50 * 1024 * 1024) // 50MB chunks
            .setParallel(4)
            .setVerifyChecksum(true)
            .setOnProgress(p -> {
                System.out.printf("Progress: %.1f%%%n", p.getPercent());
                System.out.println("Speed: " + p.getSpeedFormatted());
                System.out.println("ETA: " + p.getEtaFormatted());
            })
    );

    System.out.println("Uploaded: " + result.getBrowserDownloadUrl());
}

Using ChunkedUpload Directly

For more control over the upload process:

import io.gitea.sdk.GiteaClient;
import io.gitea.sdk.ChunkedUpload;
import io.gitea.sdk.models.*;

var client = new GiteaClient("https://gitea.example.com", "your_token");

var upload = client.createChunkedUpload("owner", "repo", 123L,
    new ChunkedUploadOptions()
        .setChunkSize(50 * 1024 * 1024)
        .setParallel(4)
        .setOnProgress(p -> System.out.printf("%.1f%%%n", p.getPercent()))
);

try (var stream = new FileInputStream("file.tar.gz")) {
    var fileSize = new java.io.File("file.tar.gz").length();
    var result = upload.upload(stream, "file.tar.gz", fileSize);
    System.out.println("Success: " + result.getBrowserDownloadUrl());
} catch (UploadException e) {
    // Upload failed, can retry later
    System.out.println("Resume with session: " + upload.getSession().getId());
}

API Reference

GiteaClient

Constructor

// With token
var client = new GiteaClient("https://gitea.example.com", "your_api_token");

// With custom HttpClient
var httpClient = HttpClient.newBuilder()
    .connectTimeout(Duration.ofSeconds(60))
    .build();
var client = new GiteaClient("https://gitea.example.com", "your_api_token", httpClient);

User Methods

• getCurrentUser() - Get authenticated user
• getUser(username) - Get user by username

Repository Methods

• getRepository(owner, repo) - Get repository
• listUserRepositories(username) - List user's repositories

Release Methods

• getRelease(owner, repo, releaseId) - Get release by ID
• getReleaseByTag(owner, repo, tag) - Get release by tag
• listReleases(owner, repo) - List all releases

Upload Methods

• uploadReleaseAsset(...) - Upload release asset with chunked upload
• createChunkedUpload(owner, repo, releaseId, options) - Create upload handler
• getUploadSession(sessionId) - Get upload session status
• cancelUpload(sessionId) - Cancel upload session

Error Handling

import io.gitea.sdk.GiteaClient;
import io.gitea.sdk.exceptions.*;

var client = new GiteaClient("https://gitea.example.com", "your_token");

try {
    var repo = client.getRepository("owner", "nonexistent");
} catch (NotFoundException e) {
    System.out.println("Repository not found: " + e.getMessage());
} catch (AuthenticationException e) {
    System.out.println("Authentication failed: " + e.getMessage());
} catch (UploadException e) {
    System.out.println("Upload failed: " + e.getMessage());
    System.out.println("Session: " + e.getSessionId() + ", Chunk: " + e.getChunkNumber());
} catch (ApiException e) {
    System.out.println("API error [" + e.getCode() + "]: " + e.getMessage());
} catch (GiteaException e) {
    System.out.println("Error: " + e.getMessage());
}

Thread Safety

The GiteaClient is thread-safe and can be shared across multiple threads. Each ChunkedUpload instance should be used by a single thread at a time.

License

MIT License - See LICENSE file for details.