Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Fetch the endpoint spec first (see Crowdin API reference below). Then:

1. Implement the method on `<Resource>Api extends CrowdinApi`: build URLs from `this.url`, add query params with `HttpRequestConfig.buildUrlParams(...)` (overloads cap at 14 pairs), declare `throws HttpException, HttpBadRequestException`, and return `ResponseObject<T>` / `ResponseList<T>` (`Void.class` for empty responses).
2. Models are Lombok `@Data` POJOs in `<resource>/model/` — write no getters, setters, or equals by hand. Jackson is configured for field-only visibility and the codebase uses no `@JsonProperty`: field names must match the API JSON keys exactly, or values silently drop. Every list endpoint needs a `<X>ResponseList` with a hand-written static `to(...)` mapping to `ResponseList.of(...)`. Params classes extending `Pagination` need `@EqualsAndHashCode(callSuper = true)`.
3. Enums implement `EnumConverter<T>`: an instance `to(...)` plus a **static** `from(String)` that the deserializer finds by reflection — a missing `from` fails at runtime, not compile time. Polymorphic models need a deserializer registered in `JacksonJsonTransformer`; fields the API returns as `[]` instead of an object need `@JsonDeserialize(using = EmptyArrayToNullDeserializer.class)`.
3. Enums implement `EnumConverter<T>`: an instance `to(...)` plus a **static** `from(String)` that the deserializer finds by reflection — a missing `from` fails at runtime, not compile time. Polymorphic models need a deserializer registered in `JacksonJsonTransformer`. The API sends some empty objects as `[]`; `cleanObjectMapper` in `JacksonJsonTransformer` reads that as `null` for every `Map` and POJO field, so build any new deserializer's mapper from `cleanObjectMapper` to inherit it.
4. For a new resource, register it in `Client.java` with four edits: the import (alphabetical), a `private final <X>Api <x>Api;` field, and its construction in both constructors (`(Credentials)` and `(Credentials, ClientConfig)`). `@Getter` generates the accessor.
5. Test by extending `TestClient` (the test class is itself a client wired to `TestHttpClient`): implement `getMocks()` returning `RequestMock.build(url, method, requestFile, responseFile)` entries, add fixture JSON under `src/test/resources/api/<resource>/`, and call `this.get<X>Api()...`. Mocks match query params exactly (pre-encode spaces as `%20`) and compare the serialized request body against the fixture — a new optional query param must stay absent when null or existing mocks for that URL break.
6. Javadoc every public method with `@param`/`@return` and a `@see` list linking both the developer.crowdin.com and enterprise operation URLs (CI publishes Javadoc).
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
package com.crowdin.client.advisors.model;

import com.crowdin.client.core.http.impl.json.EmptyArrayToNullDeserializer;
import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
import lombok.Data;

import java.util.Date;
Expand All @@ -23,6 +21,5 @@ public class AdvisorInsight {
private List<AdvisorInsightRecommendation> recommendations;
private Date checkedAt;
private AdvisorAiRun lastAiRun;
@JsonDeserialize(using = EmptyArrayToNullDeserializer.class)
private Map<String, Object> payload;
}
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
package com.crowdin.client.advisors.model;

import com.crowdin.client.core.http.impl.json.EmptyArrayToNullDeserializer;
import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
import lombok.Data;

import java.util.Map;
Expand All @@ -11,6 +9,5 @@ public class AdvisorInsightRecommendation {

private String id;
private Boolean primary;
@JsonDeserialize(using = EmptyArrayToNullDeserializer.class)
private Map<String, Object> params;
}
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,11 @@
import java.io.IOException;
import java.util.Collection;

/**
* @deprecated no longer needed: {@link JacksonJsonTransformer} reads an empty array as {@code null}
* for every Map and POJO field
*/
@Deprecated
public class EmptyArrayToNullDeserializer extends StdDeserializer<Object> implements ContextualDeserializer {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

do we use it anywhere? can we delete it?

private JavaType type;

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,10 @@
import com.fasterxml.jackson.annotation.PropertyAccessor;
import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.cfg.CoercionAction;
import com.fasterxml.jackson.databind.cfg.CoercionInputShape;
import com.fasterxml.jackson.databind.module.SimpleModule;
import com.fasterxml.jackson.databind.type.LogicalType;
import com.fasterxml.jackson.databind.util.StdDateFormat;
import lombok.SneakyThrows;

Expand All @@ -30,6 +33,13 @@ public class JacksonJsonTransformer implements JsonTransformer {
public JacksonJsonTransformer() {
ObjectMapper cleanObjectMapper = new ObjectMapper()
.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);

// the API sends some empty objects as []; read them as null (set before copy() so derived mappers inherit it)
cleanObjectMapper.coercionConfigFor(LogicalType.Map)
.setCoercion(CoercionInputShape.EmptyArray, CoercionAction.AsNull);
cleanObjectMapper.coercionConfigFor(LogicalType.POJO)
.setCoercion(CoercionInputShape.EmptyArray, CoercionAction.AsNull);

SimpleModule enumModule = new SimpleModule()
.addDeserializer(Enum.class, new EnumDeserializer());

Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
package com.crowdin.client.organization.model;

import com.crowdin.client.core.http.impl.json.EmptyArrayToNullDeserializer;
import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
import lombok.Data;

import java.util.Date;
Expand All @@ -13,7 +11,6 @@ public class ExternalQaCheck {
private Long id;
private String name;
private String description;
@JsonDeserialize(using = EmptyArrayToNullDeserializer.class)
private Map<String, Object> config;
private Date createdAt;
private Date updatedAt;
Expand Down
Original file line number Diff line number Diff line change
@@ -1,8 +1,6 @@
package com.crowdin.client.projectsgroups.model;

import com.crowdin.client.core.http.impl.json.EmptyArrayToNullDeserializer;
import com.crowdin.client.languages.model.Language;
import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
import lombok.Data;
import lombok.EqualsAndHashCode;
import lombok.ToString;
Expand Down Expand Up @@ -42,18 +40,13 @@ public class ProjectSettings extends Project {
private NotificationSettings notificationSettings;
private Long defaultTmId;
private Long defaultGlossaryId;
@JsonDeserialize(using = EmptyArrayToNullDeserializer.class)
private Map<String, AssignedTm> assignedTms;
private List<Long> assignedGlossaries;
private List<Long> assignedStyleGuides;
@JsonDeserialize(using = EmptyArrayToNullDeserializer.class)
private TmPenalties tmPenalties;
private Boolean normalizePlaceholder;
@JsonDeserialize(using = EmptyArrayToNullDeserializer.class)
private TmPreTranslate tmPreTranslate;
@JsonDeserialize(using = EmptyArrayToNullDeserializer.class)
private MtPreTranslate mtPreTranslate;
@JsonDeserialize(using = EmptyArrayToNullDeserializer.class)
private AiPreTranslate aiPreTranslate;
/**
* @deprecated no longer part of the documented API
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
package com.crowdin.client.sourcefiles.model;

import com.crowdin.client.core.http.impl.json.EmptyArrayToNullDeserializer;
import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
import lombok.Data;

import java.util.Map;
Expand All @@ -22,6 +20,5 @@ public class FileInfo {
/**
* Custom fields (Enterprise only)
*/
@JsonDeserialize(using = EmptyArrayToNullDeserializer.class)
private Map<String, Object> fields;
}
Original file line number Diff line number Diff line change
@@ -1,8 +1,6 @@
package com.crowdin.client.sourcestrings.model;

import com.crowdin.client.core.http.impl.json.EmptyArrayToNullDeserializer;
import com.crowdin.client.sourcefiles.model.UpdateOption;
import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
import lombok.Data;

import java.util.Date;
Expand All @@ -28,7 +26,6 @@ public static class Attributes {
private String fileType;
private Integer parserVersion;
private List<Long> labelIds;
@JsonDeserialize(using = EmptyArrayToNullDeserializer.class)
private ImportOptions importOptions;
private Boolean updateStrings;
private Boolean cleanupMode;
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
package com.crowdin.client.translations.model;

import com.crowdin.client.core.http.impl.json.EmptyArrayToNullDeserializer;
import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
import lombok.Data;

import java.util.List;
Expand All @@ -17,9 +15,7 @@ public class ImportTranslationsReportResponse {
public static class TargetLanguage {
private String id;
private List<File> files;
@JsonDeserialize(using = EmptyArrayToNullDeserializer.class)
private Map<String, Integer> skipped;
@JsonDeserialize(using = EmptyArrayToNullDeserializer.class)
private Map<String, Integer> skippedQaCheckCategories;
}

Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
package com.crowdin.client.translations.model;

import com.crowdin.client.core.http.impl.json.EmptyArrayToNullDeserializer;
import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
import lombok.Data;

import java.util.List;
Expand All @@ -17,9 +15,7 @@ public class ImportTranslationsStringsBasedReportResponse {
public static class TargetLanguage {
private String id;
private List<Branch> branches;
@JsonDeserialize(using = EmptyArrayToNullDeserializer.class)
private Map<String, Integer> skipped;
@JsonDeserialize(using = EmptyArrayToNullDeserializer.class)
private Map<String, Integer> skippedQaCheckCategories;
}

Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
package com.crowdin.client.translations.model;

import com.crowdin.client.core.http.impl.json.EmptyArrayToNullDeserializer;
import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
import lombok.Data;
import java.util.List;
import java.util.Map;
Expand All @@ -17,9 +15,7 @@ public class PreTranslationReportResponse {
public static class TargetLanguage {
private String id;
private List<File> files;
@JsonDeserialize(using = EmptyArrayToNullDeserializer.class)
private Map<String, Integer> skipped;
@JsonDeserialize(using = EmptyArrayToNullDeserializer.class)
private Map<String, Integer> skippedQaCheckCategories;
}

Expand Down
Original file line number Diff line number Diff line change
@@ -1,12 +1,9 @@
package com.crowdin.client.users.model;

import com.crowdin.client.core.http.impl.json.EmptyArrayToNullDeserializer;
import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
import lombok.Data;

@Data
public class TranslatorRole {
private TranslatorRoleName name;
@JsonDeserialize(using = EmptyArrayToNullDeserializer.class)
private TranslatorRolePermissions permissions;
}
Original file line number Diff line number Diff line change
@@ -1,15 +1,12 @@
package com.crowdin.client.users.model;

import com.crowdin.client.core.http.impl.json.EmptyArrayToNullDeserializer;
import com.crowdin.client.core.model.LanguageAccessRule;
import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
import lombok.Data;

import java.util.Map;

@Data
public class TranslatorRolePermissions {
private boolean allLanguages;
@JsonDeserialize(using = EmptyArrayToNullDeserializer.class)
private Map<String, LanguageAccessRule> languagesAccess;
}
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
package com.crowdin.client.webhooks.model;

import com.crowdin.client.core.http.impl.json.EmptyArrayToNullDeserializer;
import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
import lombok.Data;

import java.util.Date;
Expand All @@ -18,7 +16,6 @@ public class OrganizationWebhook {
* Webhook headers. The API returns an empty array ({@code []}) when the webhook has no headers;
* it is represented as {@code null}, the same as a missing value.
*/
@JsonDeserialize(using = EmptyArrayToNullDeserializer.class)
private Map<String, String> headers;
private Object payload;
private Boolean isActive;
Expand Down
3 changes: 0 additions & 3 deletions src/main/java/com/crowdin/client/webhooks/model/Webhook.java
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
package com.crowdin.client.webhooks.model;

import com.crowdin.client.core.http.impl.json.EmptyArrayToNullDeserializer;
import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
import lombok.Data;

import java.util.Date;
Expand All @@ -20,7 +18,6 @@ public class Webhook {
* Webhook headers. The API returns an empty array ({@code []}) when the webhook has no headers;
* it is represented as {@code null}, the same as a missing value.
*/
@JsonDeserialize(using = EmptyArrayToNullDeserializer.class)
private Map<String, String> headers;
private Object payload;
private Boolean isActive;
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
package com.crowdin.client.core.http.impl.json;

import com.crowdin.client.glossaries.model.ConceptResponseObject;
import com.crowdin.client.glossaries.model.TermResponseObject;
import com.crowdin.client.projectsgroups.model.Project;
import com.crowdin.client.projectsgroups.model.ProjectResponseObject;
import com.crowdin.client.projectsgroups.model.ProjectSettings;
import com.crowdin.client.sourcestrings.model.SourceStringResponseObject;
import com.crowdin.client.users.model.UserResponseObject;
import com.fasterxml.jackson.databind.exc.MismatchedInputException;
import org.junit.jupiter.api.Test;

import java.util.Collections;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertInstanceOf;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;

/**
* The API sends some empty objects as {@code []}; the shared mapper must read them as {@code null}
* for every Map and POJO field, without per-field annotations.
*/
public class EmptyArrayCoercionTest {

private final JacksonJsonTransformer transformer = new JacksonJsonTransformer();

@Test
public void projectFieldsEmptyArray() {
Project project = transformer.parse("{\"data\":{\"id\":1,\"fields\":[]}}", ProjectResponseObject.class).getData();

assertEquals(1L, project.getId());
assertNull(project.getFields());
}

@Test
public void projectSettingsFieldsEmptyArray() {
Project project = transformer.parse("{\"data\":{\"id\":1,\"languageMapping\":[],\"fields\":[]}}", ProjectResponseObject.class).getData();

assertInstanceOf(ProjectSettings.class, project);
assertNull(project.getFields());
}

@Test
public void projectSettingsObjectsEmptyArray() {
ProjectSettings settings = (ProjectSettings) transformer.parse("{\"data\":{\"id\":1,\"languageMapping\":[],"
+ "\"assignedTms\":[],\"tmPreTranslate\":[],\"mtPreTranslate\":[],\"aiPreTranslate\":[]}}", ProjectResponseObject.class).getData();

assertNull(settings.getAssignedTms());
assertNull(settings.getTmPreTranslate());
assertNull(settings.getMtPreTranslate());
assertNull(settings.getAiPreTranslate());
}

@Test
public void sourceStringFieldsEmptyArray() {
assertNull(transformer.parse("{\"data\":{\"id\":1,\"fields\":[]}}", SourceStringResponseObject.class).getData().getFields());
}

@Test
public void conceptFieldsEmptyArray() {
assertNull(transformer.parse("{\"data\":{\"id\":1,\"fields\":[]}}", ConceptResponseObject.class).getData().getFields());
}

@Test
public void termFieldsEmptyArray() {
assertNull(transformer.parse("{\"data\":{\"id\":1,\"fields\":[]}}", TermResponseObject.class).getData().getFields());
}

@Test
public void userFieldsEmptyArray() {
assertNull(transformer.parse("{\"data\":{\"id\":1,\"fields\":[]}}", UserResponseObject.class).getData().getFields());
}

@Test
public void nestedObjectEmptyArray() {
assertNull(transformer.parse("{\"data\":{\"id\":1,\"sourceLanguage\":[]}}", ProjectResponseObject.class).getData().getSourceLanguage());
}

@Test
public void populatedMapStillParses() {
Project project = transformer.parse("{\"data\":{\"id\":1,\"fields\":{\"slug\":\"value\"}}}", ProjectResponseObject.class).getData();

assertEquals(Collections.singletonMap("slug", "value"), project.getFields());
}

@Test
public void emptyArrayStaysEmptyListForListFields() {
Project project = transformer.parse("{\"data\":{\"id\":1,\"targetLanguageIds\":[]}}", ProjectResponseObject.class).getData();

assertTrue(project.getTargetLanguageIds().isEmpty());
}

@Test
public void nonEmptyArrayForMapStillFails() {
assertThrows(MismatchedInputException.class,
() -> transformer.parse("{\"data\":{\"id\":1,\"fields\":[1]}}", SourceStringResponseObject.class));
}
}
Loading