Package io.github.og4dev.annotation

Annotation Interface AutoTrim

@Target(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 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.

Use Cases

  • User input fields: Names, emails, addresses where whitespace is typically unwanted
  • Search queries: Remove accidental spaces from user search inputs
  • Usernames: Ensure consistent username formatting without leading/trailing spaces
  • Reference numbers: IDs, codes, or identifiers that should not have extra whitespace
  • Categories/Tags: Taxonomy values that need consistent formatting

Example Usage


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

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

     @AutoTrim
     private String firstName;      // Trimmed: "  John  " → "John"

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

Input/Output Examples


 // Request JSON
 {
   "username": "  john_doe  ",
   "email": " [email protected] ",
   "firstName": "\t\nJohn\t\n",
   "password": "  myPass123  ",
   "bio": "  Software Developer  "
 }

 // After Deserialization
 username  = "john_doe"              // ✓ Trimmed (has @AutoTrim)
 email     = "[email protected]"      // ✓ Trimmed (has @AutoTrim)
 firstName = "John"                  // ✓ Trimmed (has @AutoTrim)
 password  = "  myPass123  "         // ✗ NOT trimmed (no annotation)
 bio       = "  Software Developer  " // ✗ NOT trimmed (no annotation)

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: 


 public class SecureDTO {
     @AutoTrim
     @XssCheck
     private String cleanInput;  // Both trimmed 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 and create 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.3.0
Author:
Pasindu OG
See Also: