# thingsboard-java-client

**Repository Path**: igss_admin/thingsboard-java-client

## Basic Information

- **Project Name**: thingsboard-java-client
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-30
- **Last Updated**: 2026-03-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ThingsBoard Java REST Clients

Auto-generated Java REST clients for ThingsBoard, built from OpenAPI specifications using [OpenAPI Generator](https://openapi-generator.tech/).

## Modules

| Module | Artifact | Description |
|--------|----------|-------------|
| `ce` | `thingsboard-ce-client` | Community Edition REST client |
| `pe` | `thingsboard-pe-client` | Professional Edition REST client |
| `paas` | `thingsboard-paas-client` | Cloud (PaaS) REST client |
| `common` | `thingsboard-client-common` | Handwritten shared code (not published separately) |

All modules share the same `org.thingsboard.client` group ID and use the `org.thingsboard.client.api` / `org.thingsboard.client.model` packages.

## Maven Coordinates

```xml
<dependency>
    <groupId>org.thingsboard.client</groupId>
    <artifactId>thingsboard-ce-client</artifactId>
    <version>4.4.0-SNAPSHOT</version>
</dependency>
```

Replace `thingsboard-ce-client` with `thingsboard-pe-client` or `thingsboard-paas-client` for other editions.

## Usage

### JWT Authentication

```java
import org.thingsboard.client.ThingsboardClient;

// Credentials — logs in automatically, refreshes tokens before expiry
ThingsboardClient client = ThingsboardClient.builder()
        .url("http://localhost:8080")
        .credentials("tenant@thingsboard.org", "tenant")
        .build();

var devices = client.getTenantDevices(10, 0, null, null, null, null);
```

### API Key Authentication

```java
ThingsboardClient client = ThingsboardClient.builder()
        .url("http://localhost:8080")
        .apiKey("your-api-key")
        .build();

var devices = client.getTenantDevices(10, 0, null, null, null, null);
```

### Deferred Login

```java
ThingsboardClient client = ThingsboardClient.builder()
        .url("http://localhost:8080")
        .build();

client.login("tenant@thingsboard.org", "tenant");
```

## API Documentation

Each published JAR includes Markdown API documentation bundled under `api-docs/` in the classpath. This covers every controller endpoint (`*ControllerApi.md`) and every model class. To extract the docs from a dependency:

```bash
jar xf thingsboard-ce-client-4.4.0-SNAPSHOT.jar api-docs/
```

The same docs are also available in each edition's `docs/` directory in this repository.

## Building

```bash
mvn compile                    # Build all modules
mvn compile -pl ce             # Build CE only
```

## Project Structure

```
thingsboard-java-client/
├── pom.xml                          # Parent POM
├── generate-client.sh               # Client generation script
├── openapitools.json                # OpenAPI Generator version config
├── license-header-template.txt      # License header for generated files
├── common/
│   ├── pom.xml                      # Compiles against CE for IDE support
│   ├── src/main/java/               # Handwritten shared code (ThingsboardClient, etc.)
│   └── docs/                        # Handwritten shared docs (tb-examples.md, etc.)
├── ce/
│   ├── pom.xml
│   ├── spec/openapi.json            # OpenAPI spec (committed)
│   ├── src/main/java/               # Generated + common sources (committed)
│   ├── docs/                        # Generated API docs + common docs (committed)
│   └── target/generated/            # Raw generator output (gitignored)
├── pe/
│   └── (same structure as ce)
└── paas/
    └── (same structure as ce)
```

The `common/` module contains handwritten classes and docs shared across all editions (e.g. `ThingsboardClient`, `tb-examples.md`).
It is not a runtime dependency — `generate-client.sh` copies its sources and docs into each edition during generation.

## Client Generation

Clients are generated from OpenAPI specification files located at `<edition>/spec/openapi.json`. 
The `generate-client.sh` script handles the full workflow: generate, post-process, apply license headers, and stage changes.

### Prerequisites

- Java 25
- Maven
- Perl (for post-processing)
- curl (for downloading the generator JAR on first run)

```
Usage: ./generate-client.sh [options] <edition> [base-url]

Arguments:
  edition    ce | pe | paas | all
  base-url   Optional. Fetches spec from <base-url>/v3/api-docs/thingsboard
             and updates the local spec file before generation.
             Not supported with "all".

Options:
  --verbose  Show full generator output (per-file writes, operations, etc.)
  --dry-run  Generate into target/generated/ only. Skip copying to src/,
             license formatting, and git staging.
```

### Examples

```bash
./generate-client.sh ce                             # Generate CE from local spec
./generate-client.sh all                            # Generate all editions from local specs
./generate-client.sh ce http://localhost:8080       # Fetch spec from a running TB, then generate
./generate-client.sh --dry-run ce                   # Generate to target/ only, don't touch src/
./generate-client.sh --verbose ce                   # Full output, no log filtering
```

### What it does

1. Optionally fetches OpenAPI spec from a running ThingsBoard instance
2. Runs `openapi-generator-cli` (Java native HTTP client)
3. Strips auto-generated OpenAPI comment blocks from Java files
4. Copies generated `src/main/java/` and `docs/` into the module, then copies `common/` sources and docs on top
5. Applies Apache 2.0 license headers via `mvn license:format`
6. Stages all changes with `git add`

### Preserved on regeneration

- `<edition>/pom.xml`
- `<edition>/src/test/` (tests are never touched)
- `<edition>/spec/openapi.json` (only updated when `base-url` is provided)
- `common/` (handwritten shared sources and docs, copied into editions)

### Replaced on regeneration

- `<edition>/src/main/java/`
- `<edition>/docs/` (with `common/docs/` overlaid on top of generated docs)

Output log: `generate-client.log` (overwritten on each run)

## License

This project is licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).