Package io.github.og4dev.annotation

Annotation Interface AutoTrim

@Target({TYPE,FIELD}) @Retention(RUNTIME) public @interface AutoTrim
Annotation to explicitly enable automatic string trimming during JSON deserialization.

By default, the OG4Dev Spring API Response library does NOT automatically trim strings. This annotation allows you to opt-in to automatic trimming for specific fields or entire classes where removing leading and trailing whitespace is desired for data quality and consistency.

Important: When @AutoTrim is applied, XSS validation (HTML tag detection) is still performed on the trimmed value to maintain security.

Target Scopes

  • Field Level (ElementType.FIELD): Applies trimming only to the specific annotated String field.
  • Class Level (ElementType.TYPE): Applies trimming to all String fields within the annotated class globally.

Example Usage: Field Level


 public class UserRegistrationDTO {
 @AutoTrim
 private String username;       // Trimmed: "  john_doe  " → "john_doe"

 @AutoTrim
 private String email;          // Trimmed: " [email protected] " → "[email protected]"

 private String password;       // NOT trimmed (no annotation)
 private String bio;            // NOT trimmed (no annotation)
 }

Example Usage: Class Level


 @AutoTrim // Automatically applies to ALL String fields in this class!
 public class GlobalTrimDTO {
 private String firstName;      // Trimmed: "  John  " → "John"
 private String lastName;       // Trimmed: " Doe  " → "Doe"
 private String address;        // Trimmed: " 123 Main St " → "123 Main St"
 }

Input/Output Examples (Class Level)


 // Request JSON for GlobalTrimDTO
 {
 "firstName": "\t\nJohn\t\n",
 "lastName": "  Doe  ",
 "address": " 123 Main St "
 }

 // After Deserialization
 firstName = "John"                  // ✓ Trimmed (due to class-level @AutoTrim)
 lastName  = "Doe"                   // ✓ Trimmed (due to class-level @AutoTrim)
 address   = "123 Main St"           // ✓ Trimmed (due to class-level @AutoTrim)

XSS Validation Still Active

Even with @AutoTrim, all string values are still validated for XSS attacks. The following will still be rejected: 


 {"username": "  <script>alert('XSS')</script>  "}  // Rejected: Contains HTML tags
 {"email": "[email protected]<b>test</b>"}          // Rejected: Contains HTML tags

Combining with @XssCheck

You can combine @AutoTrim with @XssCheck for both behaviors: 


 @AutoTrim // Trims all fields
 public class SecureDTO {
 @XssCheck
 private String cleanInput;  // Both trimmed (from class scope) and XSS-validated
 }

How It Works

This annotation is processed by the AdvancedStringDeserializer in ApiResponseAutoConfiguration.strictJsonCustomizer(). The deserializer uses ValueDeserializer.createContextual(tools.jackson.databind.DeserializationContext, tools.jackson.databind.BeanProperty) to detect the annotation on either the field itself or its declaring class, creating a specialized instance that enables trimming.

Null Value Handling

Null values are preserved and never converted to empty strings: 


 {"name": null}      → name = null (not "")
 {"name": ""}        → name = ""
 {"name": "  "}      → name = ""   (trimmed to empty)

Performance Considerations

The trimming operation is highly optimized and adds negligible overhead (typically <0.1ms per field). The deserializer is created once per field during mapper initialization, not on every request, ensuring optimal runtime performance.

Since:
1.3.0
Version:
1.4.0
Author:
Pasindu OG
See Also: