Skip to content

Commit cd82ce0

Browse files
Merge branch 'release/4.3' into master
Takes master's OpenAPI specs and 4.4.0 version, and release/4.3's generator configuration: useSingleRequestParameter in generate-client.sh, the *Args request-object api.mustache, the flat-signature api_doc.mustache, the builder style README, and ThingsboardClient's LoginArgs call. Generated sources and docs are regenerated in the follow-up commit.
2 parents ad2faf9 + cd1405a commit cd82ce0

5 files changed

Lines changed: 60 additions & 16 deletions

File tree

‎README.md‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ All modules share the same `org.thingsboard.client` group ID and use the `org.th
1919
<dependency>
2020
<groupId>org.thingsboard.client</groupId>
2121
<artifactId>thingsboard-ce-client</artifactId>
22-
<version>4.4.0</version>
22+
<version>4.3.1.5</version>
2323
</dependency>
2424
```
2525

@@ -31,14 +31,17 @@ Replace `thingsboard-ce-client` with `thingsboard-pe-client` or `thingsboard-paa
3131

3232
```java
3333
import org.thingsboard.client.ThingsboardClient;
34+
import org.thingsboard.client.api.ThingsboardApi.GetTenantDevicesArgs;
3435

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

41-
var devices = client.getTenantDevices(10, 0, null, null, null, null);
42+
// Endpoints with parameters take a single <Method>Args request object built with a builder;
43+
// only required fields must be set, optional ones can be omitted.
44+
var devices = client.getTenantDevices(GetTenantDevicesArgs.builder().pageSize(10).page(0).build());
4245
```
4346

4447
### API Key Authentication
@@ -49,7 +52,7 @@ ThingsboardClient client = ThingsboardClient.builder()
4952
.apiKey("your-api-key")
5053
.build();
5154

52-
var devices = client.getTenantDevices(10, 0, null, null, null, null);
55+
var devices = client.getTenantDevices(GetTenantDevicesArgs.builder().pageSize(10).page(0).build());
5356
```
5457

5558
### Deferred Login
@@ -67,7 +70,7 @@ client.login("tenant@thingsboard.org", "tenant");
6770
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:
6871

6972
```bash
70-
jar xf thingsboard-ce-client-4.4.0.jar api-docs/
73+
jar xf thingsboard-ce-client-4.3.1.5.jar api-docs/
7174
```
7275

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

‎common/src/main/java/org/thingsboard/client/ThingsboardClient.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -221,7 +221,7 @@ public void login(String username, String password) throws ApiException {
221221
LoginRequest loginRequest = new LoginRequest();
222222
loginRequest.setUsername(username);
223223
loginRequest.setPassword(password);
224-
LoginResponse response = login(loginRequest);
224+
LoginResponse response = login(LoginArgs.builder().loginRequest(loginRequest).build());
225225
auth.onLogin(username, password, response);
226226
}
227227

‎generate-client.sh‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -156,7 +156,7 @@ generate() {
156156
--api-package "$BASE_PACKAGE.api" \
157157
--model-package "$BASE_PACKAGE.model" \
158158
--invoker-package "$BASE_PACKAGE" \
159-
--additional-properties hideGenerationTimestamp=true \
159+
--additional-properties hideGenerationTimestamp=true,useSingleRequestParameter=true \
160160
--global-property apiTests=false,modelTests=false,modelDocs=false,apiDocs=false \
161161
--schema-mappings JsonNode="$JACKSON_JSON_NODE" \
162162
--import-mappings JsonNode="$JACKSON_JSON_NODE" \
@@ -174,7 +174,7 @@ generate() {
174174
--api-package "$BASE_PACKAGE.api" \
175175
--model-package "$BASE_PACKAGE.model" \
176176
--invoker-package "$BASE_PACKAGE" \
177-
--additional-properties hideGenerationTimestamp=true \
177+
--additional-properties hideGenerationTimestamp=true,useSingleRequestParameter=true \
178178
--global-property apis,models,supportingFiles=false,apiTests=false,modelTests=false \
179179
--schema-mappings JsonNode="$JACKSON_JSON_NODE" \
180180
--import-mappings JsonNode="$JACKSON_JSON_NODE" \

‎openapi/api.mustache‎

Lines changed: 44 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -224,7 +224,7 @@ public class {{classname}} {
224224
/**
225225
* {{summary}}
226226
* {{notes}}
227-
* @param apiRequest {@link API{{#lambda.titlecase}}{{operationId}}{{/lambda.titlecase}}Request}
227+
* @param apiRequest {@link {{#lambda.titlecase}}{{operationId}}{{/lambda.titlecase}}Args}
228228
{{#returnType}}
229229
* @return {{#asyncNative}}CompletableFuture&lt;{{/asyncNative}}{{returnType}}{{#asyncNative}}&gt;{{/asyncNative}}
230230
{{/returnType}}
@@ -245,7 +245,8 @@ public class {{classname}} {
245245
{{#isDeprecated}}
246246
@Deprecated
247247
{{/isDeprecated}}
248-
public {{#returnType}}{{#asyncNative}}CompletableFuture<{{{returnType}}}>{{/asyncNative}}{{^asyncNative}}{{{returnType}}}{{/asyncNative}}{{/returnType}}{{^returnType}}{{#asyncNative}}CompletableFuture<Void>{{/asyncNative}}{{^asyncNative}}void{{/asyncNative}}{{/returnType}} {{operationId}}(API{{#lambda.titlecase}}{{operationId}}{{/lambda.titlecase}}Request apiRequest) throws ApiException {
248+
@SuppressWarnings({"deprecation", "removal"})
249+
public {{#returnType}}{{#asyncNative}}CompletableFuture<{{{returnType}}}>{{/asyncNative}}{{^asyncNative}}{{{returnType}}}{{/asyncNative}}{{/returnType}}{{^returnType}}{{#asyncNative}}CompletableFuture<Void>{{/asyncNative}}{{^asyncNative}}void{{/asyncNative}}{{/returnType}} {{operationId}}({{#lambda.titlecase}}{{operationId}}{{/lambda.titlecase}}Args apiRequest) throws ApiException {
249250
{{#allParams}}
250251
{{>nullable_var_annotations}}{{! prevent indent}}
251252
{{{dataType}}} {{paramName}} = apiRequest.{{paramName}}();
@@ -270,7 +271,7 @@ public class {{classname}} {
270271
/**
271272
* {{summary}}
272273
* {{notes}}
273-
* @param apiRequest {@link API{{#lambda.titlecase}}{{operationId}}{{/lambda.titlecase}}Request}
274+
* @param apiRequest {@link {{#lambda.titlecase}}{{operationId}}{{/lambda.titlecase}}Args}
274275
* @param headers Optional headers to include in the request
275276
* @return {{#asyncNative}}CompletableFuture&lt;{{/asyncNative}}ApiResponse&lt;{{returnType}}{{^returnType}}Void{{/returnType}}&gt;{{#asyncNative}}&gt;{{/asyncNative}}
276277
* @throws ApiException if fails to make API call
@@ -285,7 +286,8 @@ public class {{classname}} {
285286
{{#isDeprecated}}
286287
@Deprecated
287288
{{/isDeprecated}}
288-
public {{#asyncNative}}CompletableFuture<{{/asyncNative}}ApiResponse<{{{returnType}}}{{^returnType}}Void{{/returnType}}>{{#asyncNative}}>{{/asyncNative}} {{operationId}}WithHttpInfo(API{{#lambda.titlecase}}{{operationId}}{{/lambda.titlecase}}Request apiRequest, Map<String, String> headers) throws ApiException {
289+
@SuppressWarnings({"deprecation", "removal"})
290+
public {{#asyncNative}}CompletableFuture<{{/asyncNative}}ApiResponse<{{{returnType}}}{{^returnType}}Void{{/returnType}}>{{#asyncNative}}>{{/asyncNative}} {{operationId}}WithHttpInfo({{#lambda.titlecase}}{{operationId}}{{/lambda.titlecase}}Args apiRequest, Map<String, String> headers) throws ApiException {
289291
{{#allParams}}
290292
{{{dataType}}} {{paramName}} = apiRequest.{{paramName}}();
291293
{{/allParams}}
@@ -309,17 +311,31 @@ public class {{classname}} {
309311
{{/asyncNative}}
310312
{{/returnType}}
311313
* @throws ApiException if fails to make API call
314+
{{#hasParams}}
315+
* @deprecated Use {@link #{{operationId}}({{#lambda.titlecase}}{{operationId}}{{/lambda.titlecase}}Args)} instead.
316+
* This overload passes each parameter positionally, so its signature changes whenever a
317+
* parameter is added to this endpoint — breaking source and binary compatibility for
318+
* existing callers on version upgrades. The request-object overload stays compatible because
319+
* new parameters are added as optional builder fields. Scheduled for removal in a future release.
320+
{{/hasParams}}
321+
{{^hasParams}}
312322
{{#isDeprecated}}
313323
* @deprecated
314324
{{/isDeprecated}}
325+
{{/hasParams}}
315326
{{#externalDocs}}
316327
* {{description}}
317328
* @see <a href="{{url}}">{{summary}} Documentation</a>
318329
{{/externalDocs}}
319330
*/
331+
{{#hasParams}}
332+
@Deprecated(forRemoval = true)
333+
{{/hasParams}}
334+
{{^hasParams}}
320335
{{#isDeprecated}}
321336
@Deprecated
322337
{{/isDeprecated}}
338+
{{/hasParams}}
323339
public {{#returnType}}{{#asyncNative}}CompletableFuture<{{{returnType}}}>{{/asyncNative}}{{^asyncNative}}{{{returnType}}}{{/asyncNative}}{{/returnType}}{{^returnType}}{{#asyncNative}}CompletableFuture<Void>{{/asyncNative}}{{^asyncNative}}void{{/asyncNative}}{{/returnType}} {{operationId}}({{#allParams}}{{>nullable_var_annotations}} {{{dataType}}} {{paramName}}{{^-last}}, {{/-last}}{{/allParams}}) throws ApiException {
324340
{{^asyncNative}}
325341
{{#returnType}}ApiResponse<{{{.}}}> localVarResponse = {{/returnType}}{{operationId}}WithHttpInfo({{#allParams}}{{paramName}}{{^-last}}, {{/-last}}{{/allParams}}{{#hasParams}}, {{/hasParams}}null);
@@ -347,17 +363,31 @@ public class {{classname}} {
347363
* @param headers Optional headers to include in the request
348364
* @return {{#asyncNative}}CompletableFuture&lt;{{/asyncNative}}ApiResponse&lt;{{returnType}}{{^returnType}}Void{{/returnType}}&gt;{{#asyncNative}}&gt;{{/asyncNative}}
349365
* @throws ApiException if fails to make API call
366+
{{#hasParams}}
367+
* @deprecated Use {@link #{{operationId}}({{#lambda.titlecase}}{{operationId}}{{/lambda.titlecase}}Args)} instead.
368+
* This overload passes each parameter positionally, so its signature changes whenever a
369+
* parameter is added to this endpoint — breaking source and binary compatibility for
370+
* existing callers on version upgrades. The request-object overload stays compatible because
371+
* new parameters are added as optional builder fields. Scheduled for removal in a future release.
372+
{{/hasParams}}
373+
{{^hasParams}}
350374
{{#isDeprecated}}
351375
* @deprecated
352376
{{/isDeprecated}}
377+
{{/hasParams}}
353378
{{#externalDocs}}
354379
* {{description}}
355380
* @see <a href="{{url}}">{{summary}} Documentation</a>
356381
{{/externalDocs}}
357382
*/
383+
{{#hasParams}}
384+
@Deprecated(forRemoval = true)
385+
{{/hasParams}}
386+
{{^hasParams}}
358387
{{#isDeprecated}}
359388
@Deprecated
360389
{{/isDeprecated}}
390+
{{/hasParams}}
361391
public {{#asyncNative}}CompletableFuture<{{/asyncNative}}ApiResponse<{{{returnType}}}{{^returnType}}Void{{/returnType}}>{{#asyncNative}}>{{/asyncNative}} {{operationId}}WithHttpInfo({{#allParams}}{{>nullable_var_annotations}} {{{dataType}}} {{paramName}}{{^-last}}, {{/-last}}{{/allParams}}{{#hasParams}}, {{/hasParams}}Map<String, String> headers) throws ApiException {
362392
{{^asyncNative}}
363393
HttpRequest.Builder localVarRequestBuilder = {{operationId}}RequestBuilder({{#allParams}}{{paramName}}{{^-last}}, {{/-last}}{{/allParams}}{{#hasParams}}, {{/hasParams}}headers);
@@ -792,7 +822,7 @@ public class {{classname}} {
792822
{{#vendorExtensions.x-group-parameters}}
793823
{{#hasParams}}
794824

795-
public static final class API{{#lambda.titlecase}}{{operationId}}{{/lambda.titlecase}}Request {
825+
public static final class {{#lambda.titlecase}}{{operationId}}{{/lambda.titlecase}}Args {
796826
{{#requiredParams}}
797827
{{>nullable_var_annotations}}{{! prevent indent}}
798828
private {{{dataType}}} {{paramName}}; // {{description}} (required)
@@ -802,7 +832,7 @@ public class {{classname}} {
802832
private {{{dataType}}} {{paramName}}; // {{description}} (optional{{^isContainer}}{{#defaultValue}}, default to {{.}}{{/defaultValue}}{{/isContainer}})
803833
{{/optionalParams}}
804834

805-
private API{{#lambda.titlecase}}{{operationId}}{{/lambda.titlecase}}Request(Builder builder) {
835+
private {{#lambda.titlecase}}{{operationId}}{{/lambda.titlecase}}Args(Builder builder) {
806836
{{#requiredParams}}
807837
this.{{paramName}} = builder.{{paramName}};
808838
{{/requiredParams}}
@@ -816,7 +846,7 @@ public class {{classname}} {
816846
return {{paramName}};
817847
}
818848
{{/allParams}}
819-
public static Builder newBuilder() {
849+
public static Builder builder() {
820850
return new Builder();
821851
}
822852

@@ -834,8 +864,13 @@ public class {{classname}} {
834864
return this;
835865
}
836866
{{/allParams}}
837-
public API{{#lambda.titlecase}}{{operationId}}{{/lambda.titlecase}}Request build() {
838-
return new API{{#lambda.titlecase}}{{operationId}}{{/lambda.titlecase}}Request(this);
867+
public {{#lambda.titlecase}}{{operationId}}{{/lambda.titlecase}}Args build() {
868+
{{#requiredParams}}
869+
if (this.{{paramName}} == null) {
870+
throw new IllegalArgumentException("Required parameter '{{paramName}}' is not set for {{operationId}}");
871+
}
872+
{{/requiredParams}}
873+
return new {{#lambda.titlecase}}{{operationId}}{{/lambda.titlecase}}Args(this);
839874
}
840875
}
841876
}

‎openapi/api_doc.mustache‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,12 @@
1717

1818
`ThingsboardClient` methods:
1919

20+
> Every method that takes input also has a request-object overload — `<method>(<Method>Args args)`,
21+
> built via `<Method>Args.builder()...build()`. The `*Args` classes are nested in `ThingsboardApi`,
22+
> e.g. `import org.thingsboard.client.api.ThingsboardApi.SaveDeviceArgs;`. Prefer that overload in
23+
> new code: adding an optional parameter to an endpoint changes the flat signatures documented
24+
> below, but only adds a builder field to `*Args`.
25+
2026
```
2127
{{#operations}}{{#operation}}{{#returnType}}{{{.}}} {{/returnType}}{{^returnType}}void {{/returnType}}{{operationId}}({{#allParams}}{{#required}}@Nonnull {{/required}}{{^required}}@Nullable {{/required}}{{{dataType}}} {{{paramName}}}{{^-last}}, {{/-last}}{{/allParams}}) // {{{summary}}}
2228
{{/operation}}{{/operations}}```

0 commit comments

Comments
 (0)