DEV Community: Anh Trần Tuấn

Design Multi-Step Forms Efficiently on the Server-Side with Java

Anh Trần Tuấn — Wed, 13 Aug 2025 09:00:22 +0000

1. Understanding Multi-Step Forms on the Server-Side

A multi-step form breaks a single large form into smaller, sequential steps. Each step collects a subset of data, and users proceed through each step until completion. On the server side, this requires managing:

State across steps to ensure continuity.
Validation for each step's data.
Error handling to guide users back when issues arise.

2. Core Approach to Implementing Multi-Step Forms

Let’s dive into an effective implementation using Spring MVC as the server-side framework.

2.1 Structuring the Form Flow

The first step is to define how the form progresses across steps. Each step should be represented by a dedicated endpoint:

@Controller
@RequestMapping("/multi-step-form")
public class MultiStepFormController {

    @GetMapping("/step1")
    public String showStep1(Model model) {
        model.addAttribute("formData", new FormData());
        return "step1";
    }

    @PostMapping("/step1")
    public String handleStep1(@ModelAttribute FormData formData, HttpSession session) {
        session.setAttribute("formData", formData); // Save data in session
        return "redirect:/multi-step-form/step2"; // Redirect to the next step
    }

    @GetMapping("/step2")
    public String showStep2(HttpSession session, Model model) {
        FormData formData = (FormData) session.getAttribute("formData");
        if (formData == null) {
            return "redirect:/multi-step-form/step1"; // Redirect to step 1 if session is empty
        }
        model.addAttribute("formData", formData);
        return "step2";
    }

    @PostMapping("/step2")
    public String handleStep2(@ModelAttribute FormData formData, HttpSession session) {
        session.setAttribute("formData", formData);
        return "redirect:/multi-step-form/step3";
    }
}

This setup ensures that each step can access the data submitted in the previous steps via the session.

2.2 Managing State

State management is central to server-side multi-step forms. HTTP sessions are commonly used to store the data for the duration of the form:

session.setAttribute("formData", formData);
FormData formData = (FormData) session.getAttribute("formData");

Consideration: Sessions are memory-intensive. Configure session timeouts carefully, especially for large-scale applications. For better scalability, consider persisting data in a database after each step.

2.3 Validating Each Step

Validation is essential to prevent invalid data from propagating to subsequent steps. Use Spring’s validation framework to handle this:

Step 1 Validation Example:

@Component
public class Step1Validator implements Validator {

    @Override
    public boolean supports(Class<?> clazz) {
        return FormData.class.isAssignableFrom(clazz);
    }

    @Override
    public void validate(Object target, Errors errors) {
        FormData formData = (FormData) target;
        if (formData.getName() == null || formData.getName().isEmpty()) {
            errors.rejectValue("name", "field.required", "Name is required");
        }
    }
}

Integrate the validator into the controller:

@PostMapping("/step1")
public String handleStep1(@ModelAttribute @Valid FormData formData, BindingResult result, HttpSession session) {
    if (result.hasErrors()) {
        return "step1"; // Return to the same step with error messages
    }
    session.setAttribute("formData", formData);
    return "redirect:/multi-step-form/step2"; // Proceed to the next step
}

This modular validation ensures each step can handle its specific requirements independently.

2.4 Navigating Between Steps

Navigation logic ensures that users don’t skip steps unintentionally. Use server-side checks to validate the current state:

@GetMapping("/step2")
public String showStep2(HttpSession session, Model model) {
    FormData formData = (FormData) session.getAttribute("formData");
    if (formData == null) {
        return "redirect:/multi-step-form/step1"; // Redirect to step 1
    }
    model.addAttribute("formData", formData);
    return "step2";
}

By redirecting users to the appropriate step, we prevent navigation errors and ensure a smooth flow.

3. Enhancing the Multi-Step Form

3.1 Persisting Data for Scalability

Instead of relying entirely on sessions, persist form data into a database after each step. This ensures the form can resume even if the session is lost:

@Entity
public class FormData {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String name;
    private String address;
    // Additional fields
}

Save the form data during each step:

@PostMapping("/step2")
public String handleStep2(@ModelAttribute @Valid FormData formData, BindingResult result) {
    if (result.hasErrors()) {
        return "step2";
    }
    formDataRepository.save(formData);
    return "redirect:/multi-step-form/step3";
}

3.2 Providing Meaningful Feedback

A multi-step form must provide clear feedback to users at every step. Use error messages and progress indicators to guide the user.

<!-- Progress Indicator -->
<div>
    <p>Step 2 of 3</p>
</div>

<!-- Display Errors -->
<div th:if="${#fields.hasErrors()}">
    <p th:each="err : ${#fields.errors('name')}" th:text="${err}"></p>
</div>

3.3 Handling Long-Running Processes

If a step involves long-running tasks, such as uploading files or calling external APIs, use asynchronous processing:

@PostMapping("/step3")
public CompletableFuture<String> handleStep3(@ModelAttribute FormData formData) {
    return CompletableFuture.supplyAsync(() -> {
        externalService.processData(formData);
        return "redirect:/multi-step-form/complete";
    });
}

This approach prevents blocking and improves user experience.

4. Best Practices

Keep Each Step Focused

Design each step to collect only the data necessary for that stage. Avoid overwhelming users with too many fields.

Secure Data

Protect the form data with CSRF tokens and secure session management practices to prevent tampering.

Test for Edge Cases

Thoroughly test scenarios like session expiry, incomplete data, and invalid submissions to ensure resilience.

5. Conclusion

Implementing an effective multi-step form on the server side with Java requires attention to detail in state management, validation, and navigation. By following the techniques outlined in this article, you can build scalable and user-friendly forms tailored to your application’s needs.

Have questions or need clarification? Leave a comment below, and I’ll be happy to help!

Read posts more at : Design Multi-Step Forms Efficiently on the Server-Side with Java

Secrets to Masking Sensitive Data Before Sending to the Frontend in Java

Anh Trần Tuấn — Tue, 12 Aug 2025 09:00:18 +0000

1. Why Masking Sensitive Data is Essential

Masking data refers to transforming sensitive information into a partially or entirely obfuscated format to prevent unauthorized access or exposure. Before diving into the technical aspects, it's crucial to understand why this practice matters.

Protecting User Privacy

User privacy laws such as GDPR and CCPA enforce strict guidelines on how personal data should be handled. Masking data helps businesses comply with these regulations by ensuring only non-identifiable data is shared.

Mitigating Security Risks

Even if your backend is secure, exposing sensitive data in its raw form to the frontend increases the attack surface. Masking sensitive information significantly reduces the potential damage caused by data leaks.

2. Techniques for Masking Data in Java

Java provides robust libraries and tools to implement masking strategies effectively. Here, we’ll cover various approaches, from basic manual masking to leveraging libraries.

2.1 Basic Manual Masking

The simplest way to mask data is to manually replace specific characters with symbols such as *.

Code Example: Masking a Credit Card Number

public class DataMaskingUtil {

    public static String maskCreditCard(String creditCardNumber) {
        if (creditCardNumber == null || creditCardNumber.length() < 6) {
            throw new IllegalArgumentException("Invalid credit card number");
        }

        int prefixLength = 4;
        int suffixLength = 4;
        String prefix = creditCardNumber.substring(0, prefixLength);
        String suffix = creditCardNumber.substring(creditCardNumber.length() - suffixLength);
        String masked = "*".repeat(creditCardNumber.length() - prefixLength - suffixLength);

        return prefix + masked + suffix;
    }

    public static void main(String[] args) {
        String cardNumber = "1234567812345678";
        System.out.println(maskCreditCard(cardNumber)); // Output: 1234 ******** 5678
    }
}

Explanation:

The prefix and suffix are retained for identification purposes.
The rest of the digits are replaced with *, ensuring sensitive parts remain hidden.

2.2 Using Regular Expressions for Flexible Masking

Regular expressions provide a powerful way to mask patterns in strings, such as email addresses or Social Security numbers.

Code Example: Masking an Email Address

public class EmailMaskingUtil {

    public static String maskEmail(String email) {
        if (email == null || !email.contains("@")) {
            throw new IllegalArgumentException("Invalid email address");
        }

        String[] parts = email.split("@");
        String localPart = parts[0];
        String domain = parts[1];

        String maskedLocalPart = localPart.charAt(0) + "*".repeat(Math.max(0, localPart.length() - 2)) + localPart.charAt(localPart.length() - 1);

        return maskedLocalPart + "@" + domain;
    }

    public static void main(String[] args) {
        String email = "john.doe@example.com";
        System.out.println(maskEmail(email)); // Output: j ******* e@example.com
    }
}

Explanation:

Only the first and last characters of the local part are exposed.
Regular expressions split the email into identifiable components for flexible manipulation.

2.3 Masking JSON Data Using Libraries

When handling structured data, like JSON, masking requires more sophisticated tools. Libraries such as Jackson can be extended to mask sensitive fields dynamically.

Code Example: Masking Fields in JSON

import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;

class User {
    @JsonProperty("name")
    private String name;

    @JsonProperty("creditCard")
    private String creditCard;

    public User(String name, String creditCard) {
        this.name = name;
        this.creditCard = creditCard;
    }

    public String getName() {
        return name;
    }

    public String getMaskedCreditCard() {
        return DataMaskingUtil.maskCreditCard(this.creditCard);
    }
}

public class JsonMaskingDemo {
    public static void main(String[] args) throws JsonProcessingException {
        User user = new User("John Doe", "1234567812345678");
        ObjectMapper mapper = new ObjectMapper();
        System.out.println(mapper.writeValueAsString(user)); 
        // Output: {"name":"John Doe","creditCard":"1234 ******** 5678"}
    }
}

Explanation:

Sensitive fields such as credit card numbers are masked during serialization.
Custom masking logic is applied using utility functions.

3. Best Practices for Data Masking

Masking data effectively requires more than writing code. Best practices ensure robustness and compliance.

Mask at the Right Layer

Data should ideally be masked at the service layer before it reaches the API response. This ensures the backend itself doesn’t leak sensitive information.

Audit and Monitor Logs

Make sure your logging systems don’t inadvertently capture sensitive data before masking. Use log sanitizers to handle this.

4. Advanced Techniques: Leveraging Frameworks

Frameworks like Spring provide built-in mechanisms for masking data in specific scenarios, such as logging.

4.1 Masking Sensitive Data in Spring Logs

Spring Boot’s Logback allows you to customize log patterns and mask sensitive fields.

Configuration Example

<configuration>
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss} %-5level %logger{36} - %replace(%msg){'\d{16}', ' ****'}%n</pattern>
        </encoder>
    </appender>
    <root level="info">
        <appender-ref ref="CONSOLE" />
    </root>
</configuration>

5. Conclusion

Masking sensitive data is a critical part of any secure application. By using manual techniques, regular expressions, or powerful libraries, Java developers can ensure sensitive information remains hidden from unauthorized eyes. Remember, this is just one layer of defense in a multi-layered security strategy.

Do you have questions or unique scenarios regarding masking data? Feel free to comment below—I’d be happy to discuss and provide further insights!

Read posts more at : Secrets to Masking Sensitive Data Before Sending to the Frontend in Java

Reasons and Ways to Fix 'Required a Bean That Could Not Be Found' in Spring Boot

Anh Trần Tuấn — Sun, 10 Aug 2025 09:00:08 +0000

1. What Does 'Required a Bean That Could Not Be Found' Mean?

Spring Boot relies on dependency injection to wire beans together. When a component or class requires a bean (via @Autowired or constructor injection), Spring searches for it in the application context. If it cannot find the required bean, this error occurs.

The error might look something like this:

Caused by: org.springframework.beans.factory.NoSuchBeanDefinitionException:
No qualifying bean of type 'com.example.service.MyService' available.

This indicates that Spring could not locate a bean of type MyService to inject into the dependent class.

2. Common Cause: Missing Bean Definition

2.1 Example of the Problem

Consider the following scenario:

@RestController
public class MyController {

    private final MyService myService;

    @Autowired
    public MyController(MyService myService) {
        this.myService = myService;
    }

    @GetMapping("/hello")
    public String sayHello() {
        return myService.getMessage();
    }
}

And the MyService class:

public class MyService {
    public String getMessage() {
        return "Hello, Spring!";
    }
}

When you run the application, it throws the error:

No qualifying bean of type 'com.example.service.MyService' available.

The problem? Spring does not know about MyService because it is not a Spring-managed bean.

2.2 Step-by-Step Solution

To fix this, you must annotate MyService with a Spring stereotype such as @Component, @Service, or define it explicitly in a configuration class.

Option 1: Annotating with @Service

@Service
public class MyService {
    public String getMessage() {
        return "Hello, Spring!";
    }
}

This makes Spring recognize MyService as a bean and adds it to the application context.

Option 2: Explicit Configuration with @bean

Alternatively, if you prefer not to use annotations, define the bean in a configuration class:

@Configuration
public class AppConfig {

    @Bean
    public MyService myService() {
        return new MyService();
    }
}

Spring will now instantiate MyService and make it available for injection.

3. Debugging the Error: Identifying the Root Cause

To efficiently debug this error, follow these steps:

3.1 Enable Debug Logs

Enable debug logging to understand how Spring processes your beans. Add this to your application.properties:

logging.level.org.springframework=DEBUG

This will log bean creation details and can reveal why a particular bean is missing.

3.2 Check for Bean Scanning Issues

Spring Boot only scans the package of the main application class (@SpringBootApplication) and its sub-packages. If your bean is in a different package, Spring won’t detect it.

Example of the Problem:

@SpringBootApplication
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

Here, if MyService is in com.example.service but the main class is in com.example.app, the bean won’t be detected.

Solution:

Specify the package explicitly using @ComponentScan:

@SpringBootApplication
@ComponentScan(basePackages = {"com.example.service", "com.example.app"})
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

4. Advanced Scenarios

4.1 Missing Qualifier for Multiple Beans

If multiple beans of the same type exist and Spring cannot determine which one to inject, you may still encounter this error.

Example:

@Service
public class MyServiceA implements MyService {
    public String getMessage() {
        return "Message from Service A";
    }
}

@Service
public class MyServiceB implements MyService {
    public String getMessage() {
        return "Message from Service B";
    }
}

@RestController
public class MyController {

    private final MyService myService;

    @Autowired
    public MyController(MyService myService) {
        this.myService = myService;
    }
}

Error:

No qualifying bean of type 'com.example.service.MyService' available: expected single matching bean but found 2: myServiceA,myServiceB

Solution: Use @Qualifier

@RestController
public class MyController {

    private final MyService myService;

    @Autowired
    public MyController(@Qualifier("myServiceA") MyService myService) {
        this.myService = myService;
    }
}

Here, @Qualifier specifies which implementation to use.

4.2 Conditional Beans

Conditional annotations like @ConditionalOnProperty or @profile might inadvertently exclude a bean.

Example:

@Bean
@ConditionalOnProperty(name = "feature.enabled", havingValue = "true")
public MyService myService() {
    return new MyService();
}

If feature.enabled=true is missing in application.properties, the bean won’t be loaded.

Solution:

Ensure the required conditions are met in the configuration.

5. Best Practices to Avoid This Error

Always Annotate Bean Classes Properly

Use annotations like @Component, @Service, @Repository, or @Configuration to make Spring recognize your beans.

Be Explicit About Scans

For large projects, explicitly define @ComponentScan to avoid bean scanning issues.

Use @Qualifier for Ambiguity

Always use @Qualifier when multiple implementations exist for the same interface.

Leverage Profiles and Conditions Carefully

Ensure that profile-specific beans or conditional beans are correctly configured and their conditions are met.

6. Conclusion

The required a bean that could not be found error is a common pitfall in Spring Boot development but is relatively straightforward to resolve with a systematic approach. By ensuring beans are properly defined, scanned, and configured, you can eliminate this issue entirely.

Have you faced this error in a unique scenario? Share your questions or experiences in the comments below, and let’s discuss solutions!

Read posts more at : Reasons and Ways to Fix 'Required a Bean That Could Not Be Found' in Spring Boot

Solving FileNotFoundException When Handling MultipartFile in Spring Boot

Anh Trần Tuấn — Sat, 09 Aug 2025 09:00:22 +0000

1. Understanding the FileNotFoundException

This exception occurs when your application attempts to access a file or directory that does not exist at the specified path. In the context of MultipartFile, this is often due to mishandling file storage or incorrect paths in your code.

What Triggers FileNotFoundException?

Temporary File Handling : MultipartFile stores uploaded files in temporary locations, which can expire unexpectedly.
Incorrect Paths : Using relative paths or incorrect directory configurations often causes the application to fail in locating the file.
Permission Issues : The application might lack sufficient permissions to access or create the intended file or directory.

1.2 A Real-Life Example of the Problem

Let’s consider a typical file upload endpoint:

@PostMapping("/upload")
public ResponseEntity<String> uploadFile(@RequestParam("file") MultipartFile file) {
    try {
        // Save the file to a specific directory
        String uploadDir = "/uploads/";
        Path filePath = Paths.get(uploadDir + file.getOriginalFilename());

        // Ensure the directory exists
        Files.createDirectories(filePath.getParent());

        // Save the file
        file.transferTo(filePath);

        return ResponseEntity.ok("File uploaded successfully!");
    } catch (IOException e) {
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                .body("Error while uploading file: " + e.getMessage());
    }
}

What Could Go Wrong?

Missing /uploads/ Directory : If /uploads/ does not exist, the FileNotFoundException occurs.
Temporary File Expiry : The MultipartFile content might not persist long enough for file.transferTo() to execute.
File System Permissions : If the server lacks write permissions, the operation fails.

1.3 Debugging the Error

To resolve the issue, follow these steps:

Enable Detailed Logging

Add debug logs around file handling operations:

log.debug("Uploading file to path: {}", filePath.toString());

Check Permissions

Run the application user with sufficient privileges:

chmod -R 755 /uploads

Test File Path

Verify the resolved path and ensure it matches expectations. For example, print the resolved path before the file operation:

System.out.println(filePath.toAbsolutePath());

2. Solutions to Handle MultipartFile Properly

2.1 Use Configurable File Storage

Hardcoding paths is risky. Instead, externalize the storage directory:

file.upload-dir=/var/uploads

Update your code to use this property:

@Value("${file.upload-dir}")
private String uploadDir;

@PostMapping("/upload")
public ResponseEntity<String> uploadFile(@RequestParam("file") MultipartFile file) {
    try {
        Path filePath = Paths.get(uploadDir + "/" + file.getOriginalFilename());
        Files.createDirectories(filePath.getParent());
        file.transferTo(filePath);
        return ResponseEntity.ok("File uploaded successfully!");
    } catch (IOException e) {
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                .body("Error while uploading file: " + e.getMessage());
    }
}

Why It Works

The property-based approach ensures flexibility.
Paths can be modified without redeploying the application.

2.2 Handle Temporary Files Explicitly

Instead of relying on the default behavior, explicitly manage temporary files:

@PostMapping("/upload")
public ResponseEntity<String> uploadFile(@RequestParam("file") MultipartFile file) {
    try {
        File tempFile = File.createTempFile("upload-", file.getOriginalFilename());
        file.transferTo(tempFile);
        // Move the file to the desired directory
        Path destination = Paths.get(uploadDir + "/" + file.getOriginalFilename());
        Files.move(tempFile.toPath(), destination, StandardCopyOption.REPLACE_EXISTING);
        return ResponseEntity.ok("File uploaded successfully!");
    } catch (IOException e) {
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                .body("Error while uploading file: " + e.getMessage());
    }
}

Why It Works

Temporary files ensure content availability during processing.
Explicit movement to the target directory prevents FileNotFoundException.

2.3 Test Scenarios Thoroughly

Always test your application in the environments it will run in (e.g., local, staging, production). Use these test cases:

Upload large files to simulate delays.
Test with restricted permissions.
Use edge cases such as uploading files with invalid names.

2.4 Embrace Exception Handling

Catch and log all file-related exceptions to provide meaningful feedback to users. Enhance the earlier example:

catch (FileNotFoundException e) {
    log.error("File not found: {}", e.getMessage());
    return ResponseEntity.status(HttpStatus.BAD_REQUEST).body("File path is invalid.");
} catch (IOException e) {
    log.error("IO Error: {}", e.getMessage());
    return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
            .body("An error occurred while processing the file.");
}

3. Best Practices for MultipartFile in Spring Boot

3.1 Always Validate the File

Check for null files and validate the file type before processing:

if (file.isEmpty() || !file.getContentType().startsWith("image/")) {
    throw new IllegalArgumentException("Invalid file. Only image files are allowed.");
}

3.2 Secure File Uploads

Avoid storing files in web-accessible directories to mitigate security risks. Instead, use a service layer to serve files. Example:

@GetMapping("/files/{filename}")
public ResponseEntity<Resource> getFile(@PathVariable String filename) {
    Path file = Paths.get(uploadDir).resolve(filename);
    Resource resource = new UrlResource(file.toUri());
    return ResponseEntity.ok()
            .contentType(MediaType.APPLICATION_OCTET_STREAM)
            .body(resource);
}

3.3 Monitor Disk Space

Use monitoring tools to track disk usage. A full disk can cause FileNotFoundException.

4. Conclusion

Handling MultipartFile properly in Spring Boot requires attention to detail, from correctly configuring file storage to implementing robust exception handling. By understanding the root causes of FileNotFoundException and adopting the solutions above, you can ensure a reliable file upload mechanism.

Have you faced similar issues with MultipartFile? Let us know in the comments below, and feel free to share any questions!

Read posts more at : Solving FileNotFoundException When Handling MultipartFile in Spring Boot

Upload Files with Special Characters to S3 Buckets and Handle Presigned URL Errors

Anh Trần Tuấn — Fri, 08 Aug 2025 09:00:25 +0000

1. Understanding the Problem

Before diving into solutions, let’s examine why files with special characters can cause issues when uploading to S3.

1.1 How S3 Handles Special Characters

Amazon S3 uses URIs (Uniform Resource Identifiers) to access objects. Certain characters—like /, @, or :—have special meanings in URIs, while others may require encoding to work properly. For instance:

Spaces are often converted to %20.
Reserved characters like ? and & can cause the URL to break if not encoded.

1.2 The Role of Presigned URLs

A presigned URL allows temporary access to S3 resources. The AWS SDK automatically generates these URLs with query parameters and signatures. However, improper handling of special characters in the file name or key can lead to:

Signature mismatch errors.
403 Forbidden responses.

1.3 Encoding and Decoding Challenges

Many developers overlook encoding requirements, leading to mismatches between how the URL is generated and consumed. Improper encoding can also result in corrupted file names on upload.

2. Methods to Upload Files with Special Characters to S3

2.1 Generating Presigned URLs Correctly

The first step is to ensure that presigned URLs are generated with proper encoding. Here’s an example in Java using the AWS SDK:

import software.amazon.awssdk.auth.credentials.ProfileCredentialsProvider;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.GeneratePresignedUrlRequest;

import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.time.Instant;
import java.util.Date;

public class S3PresignedUrlExample {
    public static void main(String[] args) {
        String bucketName = "your-bucket-name";
        String objectKey = "my file@123#.txt"; // File with special characters

        // Encode the key
        String encodedKey = URLEncoder.encode(objectKey, StandardCharsets.UTF_8);

        S3Client s3Client = S3Client.builder()
                .credentialsProvider(ProfileCredentialsProvider.create())
                .build();

        // Generate the presigned URL
        var presignedUrlRequest = GeneratePresignedUrlRequest.builder()
                .bucket(bucketName)
                .key(encodedKey)
                .expiration(Date.from(Instant.now().plusSeconds(3600)))
                .build();

        String presignedUrl = s3Client.utilities().getUrl(presignedUrlRequest).toExternalForm();
        System.out.println("Presigned URL: " + presignedUrl);
    }
}

Key Explanation:

Encoding Special Characters : Using URLEncoder.encode ensures that special characters are converted to their URI-encoded forms.
Presigned URL Expiration : The expiration time ensures temporary access, minimizing security risks.

2.2 Uploading Files Using Presigned URLs

Once the presigned URL is generated, you can use tools like curl or libraries like HttpClient in Java to upload the file. Below is an example in Java:

import java.io.File;
import java.io.IOException;
import java.net.HttpURLConnection;
import java.net.URL;

public class S3FileUpload {
    public static void main(String[] args) throws IOException {
        String presignedUrl = "https://example-bucket.s3.amazonaws.com/my%20file%40123%23.txt?AWSAccessKeyId=..."; 
        File file = new File("path/to/your/file/my file@123#.txt");

        HttpURLConnection connection = (HttpURLConnection) new URL(presignedUrl).openConnection();
        connection.setDoOutput(true);
        connection.setRequestMethod("PUT");

        // Upload file
        try (var outputStream = connection.getOutputStream();
             var inputStream = new FileInputStream(file)) {
            inputStream.transferTo(outputStream);
        }

        int responseCode = connection.getResponseCode();
        if (responseCode == 200) {
            System.out.println("File uploaded successfully.");
        } else {
            System.out.println("Failed to upload file. Response code: " + responseCode);
        }
    }
}

Key Explanation:

Presigned URL Usage : The URL includes the key, query parameters, and signature.
Handling Special Characters : The encoded key (my%20file%40123%23.txt) ensures compatibility with the S3 API.

2.3 Common Issues and Solutions

Even with the right setup, errors can occur. Below are common issues and their resolutions:

Signature Mismatch:

Cause : Inconsistent encoding between presigned URL generation and usage.
Solution : Always encode special characters and ensure both client and server handle URLs identically.

403 Forbidden:

Cause : Expired presigned URL or incorrect bucket permissions.
Solution : Ensure the URL is generated with sufficient validity and verify S3 bucket policies.

Corrupted File Names:

Cause : Improper decoding on the S3 side.
Solution : Decode the file name correctly when processing S3 events.

3. Beyond File Uploads: Related Considerations

3.1 Bucket Policies and IAM Roles

Special characters in file names may also interact with bucket policies. Always use IAM roles with the least privilege and validate permissions for specific actions like s3:PutObject.

3.2 File Metadata Handling

When uploading files, include metadata such as Content-Type and Content-Disposition to ensure the file is served correctly.

connection.setRequestProperty("Content-Type", "text/plain");
connection.setRequestProperty("Content-Disposition", "attachment; filename="my file@123#.txt"");

4. Conclusion

Uploading files with special characters to an S3 bucket is challenging but manageable with proper encoding, presigned URL generation, and error handling. By understanding how S3 processes object keys and signatures, you can avoid common pitfalls and ensure seamless uploads.

Got questions or stuck on a specific issue? Comment below, and I’ll be happy to help!

Read posts more at : Upload Files with Special Characters to S3 Buckets and Handle Presigned URL Errors

Why ‘String Cannot Be Converted to JSONObject’ Occurs and How to Fix It

Anh Trần Tuấn — Thu, 07 Aug 2025 09:00:21 +0000

1. Understanding the Error: What Does It Mean?

When Java processes JSON data using libraries like org.json or Gson, it requires the input to follow strict JSON formatting. The error String cannot be converted to JSONObject indicates that the application attempted to parse a string as a JSON object, but the string failed to meet the JSON structure requirements.

1.1 Basic Definition of JSONObject

A JSONObject in Java represents a JSON object. For example:

{
  "key": "value",
  "anotherKey": 42
}

This structure contains key-value pairs, which JSONObject can easily process. If the input string is missing required syntax, such as braces {} or is malformed, Java throws this error.

1.2 Common Causes

The string is not in valid JSON format (e.g., a plain string instead of JSON).
The string contains additional characters, such as a newline or whitespace, that prevent parsing.
The API response is unexpected, such as returning XML or plain text instead of JSON.
Improper encoding or decoding during transmission.

2. Resolving the Issue with Practical Examples

Let's address how to debug and fix this issue in Java. Each method below includes an example and a detailed explanation.

2.1 Validate the Input String

Before attempting to parse, ensure the string is valid JSON. Using a validation library or method helps avoid unnecessary exceptions.

Code Example:

import org.json.JSONObject;

public class JsonValidator {
    public static boolean isValidJson(String json) {
        try {
            new JSONObject(json);
            return true;
        } catch (Exception e) {
            return false;
        }
    }

    public static void main(String[] args) {
        String input = "{ "name": "Tuan Anh", "age": 30 }";
        if (isValidJson(input)) {
            System.out.println("Valid JSON: " + input);
        } else {
            System.out.println("Invalid JSON");
        }
    }
}

Explanation:

This code checks whether a given string is valid JSON.
If the string is invalid, you can handle it gracefully instead of letting the application crash.

2.2 Handle Unexpected API Responses

Sometimes, the error occurs because the string comes from an API that doesn’t consistently return JSON. For example, an error response might be plain text.

Code Example:

import org.json.JSONObject;

public class ApiResponseHandler {
    public static void processResponse(String response) {
        try {
            JSONObject jsonObject = new JSONObject(response);
            System.out.println("Parsed JSON: " + jsonObject);
        } catch (Exception e) {
            System.out.println("Invalid response format: " + response);
        }
    }

    public static void main(String[] args) {
        String apiResponse = "<html>Error 404: Not Found</html>"; // Simulated API response
        processResponse(apiResponse);
    }
}

Explanation:

This code demonstrates how to safeguard against non-JSON responses from APIs.
By wrapping the parsing operation in a try-catch block, it catches exceptions and logs invalid data.

2.3 Strip Unnecessary Characters

Sometimes, strings contain unwanted characters such as whitespace or escape sequences. Stripping these can help.

import org.json.JSONObject;

public class JsonCleaner {
    public static String cleanJsonString(String input) {
        return input.trim(); // Removes leading and trailing whitespace
    }

    public static void main(String[] args) {
        String rawInput = " {"key":"value"} ";
        String cleanedInput = cleanJsonString(rawInput);

        try {
            JSONObject jsonObject = new JSONObject(cleanedInput);
            System.out.println("Cleaned and Parsed JSON: " + jsonObject);
        } catch (Exception e) {
            System.out.println("Error parsing JSON");
        }
    }
}

Explanation:

This solution trims unnecessary spaces or characters from the string before parsing.
It’s particularly useful when dealing with inconsistent input formats.

3. Preventive Measures and Best Practices

Always Validate API Responses

Use libraries such as Jackson or org.json to handle JSON, but always validate the response to ensure it adheres to expected formats.

Monitor Encoding Issues

Encoding problems, especially when transferring data between systems, often cause malformed JSON. Double-check encoding standards (e.g., UTF-8).

Use a Robust JSON Library

For better error handling and more advanced features, consider using Gson or Jackson. These libraries provide better utilities for working with JSON.

import com.google.gson.JsonObject;
import com.google.gson.JsonParser;

public class GsonExample {
    public static void main(String[] args) {
        String jsonString = "{ "name": "Tuan Anh", "role": "Developer" }";

        try {
            JsonObject jsonObject = JsonParser.parseString(jsonString).getAsJsonObject();
            System.out.println("Parsed with Gson: " + jsonObject);
        } catch (Exception e) {
            System.out.println("Failed to parse JSON");
        }
    }
}

4. Common Pitfalls and Troubleshooting

Relying on Assumptions

Avoid assuming all inputs are correctly formatted. Always validate inputs before parsing.

Ignoring Exception Details

Exception messages often reveal why parsing fails. For example, an error might indicate that a specific key is missing or malformed.

Skipping API Documentation

Ensure the API's documentation specifies its response format. If not, handle all possible cases (e.g., JSON, plain text, or XML).

5. Conclusion

Handling the String cannot be converted to JSONObject error requires understanding JSON structures, validating inputs, and preparing for unexpected data. With proper preventive measures and robust error handling, you can ensure your application processes JSON data reliably. Have you faced challenges with JSON parsing in Java? Feel free to share your questions or experiences in the comments below!

Read posts more at : Why ‘String Cannot Be Converted to JSONObject’ Occurs and How to Fix It

Why Your Spring Data JPA Entity Classes Are Not Recognized and How to Fix It

Anh Trần Tuấn — Wed, 06 Aug 2025 09:00:17 +0000

1. Understanding the Issue

Spring Data JPA relies on entity classes to interact with your database. If these classes are not properly recognized, you might encounter exceptions like EntityNotFoundException or NoSuchBeanDefinitionException. These issues typically stem from misconfigurations in your project.

1.1 What Is an Entity in JPA?

An entity in JPA represents a table in the database. Each instance of the entity corresponds to a row in that table. To define an entity, the class is annotated with @Entity, and the primary key is specified using @id.

import jakarta.persistence.Entity;
import jakarta.persistence.Id;

@Entity
public class Product {
    @Id
    private Long id;
    private String name;
    private Double price;

    // Getters and Setters
}

1.2 Common Symptoms

If Spring cannot recognize your entity classes, you might encounter:

javax.persistence.PersistenceException: Unable to locate entity.
Failed application startup due to missing beans.
No operations performed on the database despite correct query logic.

2. Reasons Behind the Issue

Missing Entity Scan Configuration

Spring Boot automatically scans for entities in the same package or sub-packages as the @SpringBootApplication class. If your entities reside in a different package, they won't be detected.

Incorrect Persistence Configuration

The persistence.xml or application.properties might be missing key details about your entities.

Missing JPA Annotations

Entities must be annotated with @Entity. Without it, Spring won’t recognize the class as an entity.

Dependency Issues

If the necessary JPA dependencies are not included, the application won’t be able to process entity classes.

3. Fixing the Issue

3.1 Specify the Package in Entity Scan

If your entities are in a different package, explicitly define the package using @EntityScan in your main application class.

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.domain.EntityScan;

@SpringBootApplication
@EntityScan(basePackages = "com.example.entities")
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

3.2 Correctly Annotate Entity Classes

Ensure every entity class has the @Entity annotation and a defined primary key using @id.

3.3 Verify Dependencies

Include the necessary dependencies for Spring Data JPA in your pom.xml or build.gradle.

For Maven:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <scope>runtime</scope>
</dependency>

For Gradle:

implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
runtimeOnly 'com.h2database:h2'

3.4 Configure application.properties

Ensure the application.properties or application.yml file correctly points to your database and JPA configurations.

spring.datasource.url=jdbc:h2:mem:testdb
spring.datasource.driver-class-name=org.h2.Driver
spring.jpa.hibernate.ddl-auto=update

4. Related Concepts and Best Practices

4.1 Testing Entity Recognition

Always test your configurations with a simple repository query to ensure your entities are recognized:

@Repository
public interface ProductRepository extends JpaRepository<Product, Long> {}

Test the repository:

@SpringBootTest
public class ProductRepositoryTest {
    @Autowired
    private ProductRepository productRepository;

    @Test
    public void testSaveProduct() {
        Product product = new Product();
        product.setId(1L);
        product.setName("Sample Product");
        product.setPrice(99.99);
        productRepository.save(product);

        Optional<Product> retrieved = productRepository.findById(1L);
        assertTrue(retrieved.isPresent());
    }
}

4.2 Use @Configuration for Advanced Scanning

For more complex setups, use a custom configuration class to scan specific packages:

@Configuration
@EntityScan(basePackages = {"com.example.custom.entities"})
@EnableJpaRepositories(basePackages = {"com.example.custom.repositories"})
public class JpaConfig {}

4.3 Debugging Tips

Use @EnableJpaRepositories to ensure repositories are being scanned.

Enable debug logging for Hibernate to track entity issues:

logging.level.org.hibernate.SQL=debug
logging.level.org.hibernate.type.descriptor.sql.BasicBinder=trace

4.4 Avoid Common Pitfalls

Ensure unique table names in @Table.

Don’t forget the @GeneratedValue annotation for auto-increment IDs.

5. Conclusion

Ensuring Spring Data JPA recognizes your entity classes is critical for a seamless database integration. From annotating classes correctly to configuring package scans and dependencies, every step plays a vital role. By following the methods outlined in this article, you can resolve entity recognition issues effectively.

Do you have questions or face challenges not covered here? Comment below, and let’s discuss!

Read posts more at : Why Your Spring Data JPA Entity Classes Are Not Recognized and How to Fix It

Building a Detailed Role-Based Access Control System with Spring Security and Spring Boot

Anh Trần Tuấn — Tue, 05 Aug 2025 09:00:40 +0000

1. Introduction to Role-Based Access Control (RBAC)

RBAC is a widely adopted model where permissions are assigned to roles, and roles are assigned to users. It simplifies the management of permissions and ensures scalability in complex systems.

1.1 Why RBAC Matters

Imagine a system with hundreds of users and dozens of operations. Assigning permissions directly to users becomes a nightmare to manage. Roles abstract this complexity by grouping permissions, making it easier to maintain and audit.

1.2 Core Components of RBAC

Users : Individuals using the system.
Roles : Collections of permissions, e.g., ADMIN, USER.
Permissions : Granular actions like READ, WRITE, DELETE.

2. Setting Up the Spring Boot Application

2.1 Basic Project Configuration

First, create a Spring Boot project with the following dependencies:

Spring Security
Spring Web
Spring Data JPA
H2 Database (for demo purposes)

Your pom.xml should include:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <scope>runtime</scope>
</dependency>

2.2 Database Schema for Roles and Permissions

Define the database schema with entities for User, Role, and Permission:

@Entity
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String username;
    private String password;

    @ManyToMany(fetch = FetchType.EAGER)
    private Set<Role> roles = new HashSet<>();
}

@Entity
public class Role {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String name;

    @ManyToMany(fetch = FetchType.EAGER)
    private Set<Permission> permissions = new HashSet<>();
}

@Entity
public class Permission {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String name;
}

2.3 Populating Initial Data

Use a CommandLineRunner to seed the database with default roles and permissions:

@Bean
CommandLineRunner init(RoleRepository roleRepo, PermissionRepository permRepo, UserRepository userRepo) {
    return args -> {
        Permission readPermission = permRepo.save(new Permission("READ_PRIVILEGE"));
        Permission writePermission = permRepo.save(new Permission("WRITE_PRIVILEGE"));

        Role adminRole = new Role();
        adminRole.setName("ADMIN");
        adminRole.getPermissions().add(readPermission);
        adminRole.getPermissions().add(writePermission);
        roleRepo.save(adminRole);

        User adminUser = new User();
        adminUser.setUsername("admin");
        adminUser.setPassword(new BCryptPasswordEncoder().encode("password"));
        adminUser.getRoles().add(adminRole);
        userRepo.save(adminUser);
    };
}

3. Implementing Role-Based Authorization

3.1 Configuring Spring Security

Define a custom security configuration to enable role-based access control:

@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .csrf().disable()
            .authorizeRequests()
            .antMatchers("/admin/**").hasRole("ADMIN")
            .antMatchers("/user/**").hasRole("USER")
            .anyRequest().authenticated()
            .and()
            .httpBasic();
    }

    @Override
    protected void configure(AuthenticationManagerBuilder auth) throws Exception {
        auth.userDetailsService(customUserDetailsService())
            .passwordEncoder(new BCryptPasswordEncoder());
    }
}

3.2 Custom UserDetailsService

Implement a custom UserDetailsService to load user details from the database:

@Service
public class CustomUserDetailsService implements UserDetailsService {
    private final UserRepository userRepository;

    public CustomUserDetailsService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    @Override
    public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException {
        User user = userRepository.findByUsername(username)
            .orElseThrow(() -> new UsernameNotFoundException("User not found"));

        Set<GrantedAuthority> authorities = user.getRoles().stream()
            .flatMap(role -> role.getPermissions().stream())
            .map(permission -> new SimpleGrantedAuthority(permission.getName()))
            .collect(Collectors.toSet());

        return new org.springframework.security.core.userdetails.User(
            user.getUsername(),
            user.getPassword(),
            authorities
        );
    }
}

4. Testing the System

4.1 Secured Endpoints

Create a controller with secured endpoints:

@RestController
@RequestMapping("/admin")
public class AdminController {
    @GetMapping
    public String adminDashboard() {
        return "Welcome to Admin Dashboard";
    }
}

@RestController
@RequestMapping("/user")
public class UserController {
    @GetMapping
    public String userDashboard() {
        return "Welcome to User Dashboard";
    }
}

4.2 Testing with Postman

Use basic authentication with username admin and password password.

Access /admin: Should return Welcome to Admin Dashboard.

Access /user: Should return a 403 error.

5. Extending RBAC with Advanced Features

Hierarchical Roles

Implement role hierarchies, e.g., ADMIN inherits USER privileges.

Dynamic Permissions

Fetch permissions dynamically from the database and update security rules without restarting the application.

Auditing and Logging

Track unauthorized access attempts and log them for security analysis.

6. Conclusion

Building a detailed RBAC system with Spring Security and Spring Boot requires careful planning, but the flexibility and scalability it offers make it a worthwhile endeavor. By following the steps outlined in this guide, you can implement a robust and secure authorization mechanism tailored to your application's needs.

If you have any questions or need further clarification, feel free to leave a comment below!

Read posts more at : Building a Detailed Role-Based Access Control System with Spring Security and Spring Boot

Secrets to Optimizing and Organizing Liquibase Scripts in Spring Boot for Seamless Database Migrations

Anh Trần Tuấn — Mon, 04 Aug 2025 09:00:13 +0000

1. Understanding Liquibase in Spring Boot

1.1 What is Liquibase?

Liquibase is an open-source database schema management tool that simplifies tracking, versioning, and deploying database changes. By using XML, YAML, JSON, or SQL files called changelogs, Liquibase allows developers to apply consistent schema changes across environments.

In Spring Boot, integrating Liquibase is straightforward. Simply add the following dependency to your pom.xml:

<dependency>
    <groupId>org.liquibase</groupId>
    <artifactId>liquibase-core</artifactId>
</dependency>

With minimal configuration in application.properties, Liquibase will automatically run migrations on application startup.

1.2 The Problem with Poorly Organized Scripts

While Liquibase is a robust tool, its power can become a liability if not managed properly. Issues such as redundant scripts, conflicting changes, or overly large changelogs often lead to errors during deployment. These problems are amplified in projects involving multiple teams or microservices.

2. Secrets to Optimizing and Organizing Liquibase Scripts

2.1 Split Changelogs into Logical Units

Instead of maintaining a monolithic db.changelog-master.xml, split it into smaller, logically grouped files. For instance, separate tables, procedures, and indexes into different changelogs:

Example Directory Structure:

src/main/resources/db/changelog/
    ├── db.changelog-master.xml
    ├── tables/
    │ ├── create-user-table.xml
    │ ├── create-order-table.xml
    ├── procedures/
    │ ├── add-audit-procedure.xml
    ├── indexes/
        ├── add-index-on-user.xml

Master Changelog Example:

<databaseChangeLog>
    <include file="tables/create-user-table.xml"/>
    <include file="tables/create-order-table.xml"/>
    <include file="procedures/add-audit-procedure.xml"/>
    <include file="indexes/add-index-on-user.xml"/>
</databaseChangeLog>

Why It Works:

Improves readability and maintainability.
Reduces conflicts in teams working on different features.

2.2 Use Contexts for Environment-Specific Changes

Not all database changes apply universally across all environments. Liquibase supports contexts to filter scripts based on the environment.

<changeSet id="1" author="tuananh" context="dev">
    <createTable tableName="dev_only_table">
        <column name="id" type="int" autoIncrement="true"/>
        <column name="name" type="varchar(255)"/>
    </createTable>
</changeSet>

In application.properties:

spring.liquibase.contexts=dev

Benefit:

Contexts ensure that dev-only or staging-specific scripts do not accidentally run in production, improving safety during deployments.

3. Optimizing Liquibase Execution

Use Checksums to Prevent Unintended Changes

Liquibase uses checksums to detect whether a script has been modified after it was applied. However, developers often run into checksum mismatches. The best practice is to avoid modifying applied scripts. Instead, create a new changeSet.

Anti-Pattern:

<changeSet id="1" author="tuananh">
    <addColumn tableName="user">
        <column name="new_column" type="varchar(255)"/>
    </addColumn>
</changeSet>

If new_column changes after it’s already applied, it will cause issues. Instead, create a new changeSet:

<changeSet id="2" author="tuananh">
    <dropColumn tableName="user" columnName="new_column"/>
    <addColumn tableName="user">
        <column name="updated_column" type="varchar(255)"/>
    </addColumn>
</changeSet>

Leverage Precondition Checks

To avoid running changes in unintended states, use preconditions. Preconditions ensure that scripts are executed only when certain conditions are met.

Example:

<changeSet id="3" author="tuananh">
    <preConditions onFail="MARK_RAN">
        <not>
            <tableExists tableName="user"/>
        </not>
    </preConditions>
    <createTable tableName="user">
        <column name="id" type="int" autoIncrement="true"/>
        <column name="name" type="varchar(255)"/>
    </createTable>
</changeSet>

4. Best Practices for Collaborative Development

4.1 Naming Conventions for Scripts

Adopt a consistent naming convention for your changeSets and changelogs. Use a pattern such as
_

_

for easy tracking.

Example:

20241122_add_user_table.xml

4.2 Code Reviews for Database Changes

Just like application code, database scripts should undergo peer reviews to catch potential issues. Tools like Pull Requests in GitHub can ensure adherence to conventions.

5. Advanced Tips for Scaling Liquibase in Microservices

Isolate Databases Per Service

In microservices architectures, avoid a shared database schema. Each service should manage its database and Liquibase scripts independently.

Automate Validation in CI/CD

Integrate Liquibase checks into your CI/CD pipelines using the liquibase validate command to catch syntax errors or schema conflicts before they reach production.

6. Conclusion

By organizing Liquibase scripts logically, leveraging contexts, and incorporating best practices, you can transform your database migration process into a well-oiled machine. The examples above illustrate how small tweaks can prevent big headaches in the long run. Have any questions about Liquibase or want to share your experiences? Let me know in the comments below!

Read posts more at : Secrets to Optimizing and Organizing Liquibase Scripts in Spring Boot for Seamless Database Migrations

Secrets to Designing an Effective UserDTO in Spring Boot Applications

Anh Trần Tuấn — Sun, 03 Aug 2025 09:00:43 +0000

1. What is a UserDTO, and Why is it Important?

The UserDTO is a lightweight object used to encapsulate user-related data and transfer it between layers of an application, such as the controller, service, and repository. Unlike an entity, a DTO doesn’t map directly to the database. Instead, it focuses on delivering only the necessary data, improving performance and abstraction.

1.1 Bridging the Layers with a UserDTO

When you have a large User entity with sensitive information like passwords, exposing it directly to a client through REST APIs can be problematic. Here’s where UserDTO comes in handy—it extracts only the required fields for transmission.

Consider a typical User entity:

@Entity
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String username;
    private String email;
    private String password; // Sensitive data
    private boolean active;

    // Getters and setters
}

Here’s a corresponding UserDTO:

public class UserDTO {
    private String username;
    private String email;
    private boolean active;

    // Getters and setters
}

The UserDTO omits the password field, ensuring sensitive data doesn’t leak unintentionally.

2. Key Principles of Designing an Effective UserDTO

2.1 Minimalism: Include Only What’s Needed

A UserDTO should contain only the fields required for the specific operation. Overloading it with unnecessary fields increases payload size and complicates maintenance.

If you’re creating a user list for the admin panel, you might include fields like username and active, but omit email.

public class UserListDTO {
    private String username;
    private boolean active;

    // Getters and setters
}

2.2 Flexibility Through Nested DTOs

For complex user-related data, you can nest DTOs within a parent UserDTO. This approach is particularly useful when dealing with relationships like roles or addresses.

public class UserDTO {
    private String username;
    private String email;
    private boolean active;
    private List<RoleDTO> roles;

    // Getters and setters
}

public class RoleDTO {
    private String name;

    // Getters and setters
}

This design allows you to encapsulate related data cleanly and avoids direct dependencies on the entity structure.

3. Implementing and Mapping UserDTO in Spring Boot

To effectively implement UserDTO in a Spring Boot application, mapping between entities and DTOs is crucial.

3.1 Using Libraries Like MapStruct for Efficient Mapping

Manual mapping can be tedious and error-prone. A library like MapStruct automates this process.

Add the MapStruct dependency to your pom.xml:

<dependency>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct</artifactId>
    <version>1.5.3.Final</version>
</dependency>
<dependency>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct-processor</artifactId>
    <version>1.5.3.Final</version>
    <scope>provided</scope>
</dependency>

Create a mapper interface:

@Mapper(componentModel = "spring")
public interface UserMapper {
    UserDTO toDTO(User user);
    User toEntity(UserDTO userDTO);
}

Now, you can use the UserMapper in your service:

@Service
public class UserService {

    private final UserRepository userRepository;
    private final UserMapper userMapper;

    public UserService(UserRepository userRepository, UserMapper userMapper) {
        this.userRepository = userRepository;
        this.userMapper = userMapper;
    }

    public UserDTO getUserById(Long id) {
        User user = userRepository.findById(id).orElseThrow(() -> new RuntimeException("User not found"));
        return userMapper.toDTO(user);
    }
}

4. Advanced Considerations for UserDTO Design

4.1 Custom Validation in UserDTO

When accepting user data from external sources, validation is essential to ensure data integrity. Use annotations like @NotNull, @Email, and @Size to validate fields.

public class UserDTO {
    @NotNull
    private String username;

    @Email
    private String email;

    @Size(min = 6, message = "Password must be at least 6 characters long")
    private String password;

    private boolean active;

    // Getters and setters
}

4.2 Versioning UserDTO for API Evolution

APIs evolve, and so should DTOs. To support backward compatibility, version your DTOs when adding new fields.

// Version 1
public class UserDTO_v1 {
    private String username;
    private String email;
}

// Version 2
public class UserDTO_v2 extends UserDTO_v1 {
    private boolean active;
}

5. Best Practices for Managing UserDTO in Spring Boot

Avoid Tight Coupling Between Entity and DTO

Use a dedicated service or mapper class to handle the conversion logic. Directly coupling the entity and DTO makes your application brittle and harder to maintain.

Keep DTOs Context-Specific

Instead of using one massive UserDTO for all use cases, create context-specific DTOs like UserDetailDTO, UserListDTO, and UserUpdateDTO.

6. Conclusion

Designing an effective UserDTO in Spring Boot applications requires careful consideration of data flow, performance, and maintainability. By adhering to principles like minimalism, flexibility, and separation of concerns, you can ensure your DTOs are robust and future-proof. Tools like MapStruct simplify mapping, while practices like validation and versioning enhance reliability.

What challenges have you faced while designing DTOs? Let’s discuss in the comments below!

Read posts more at : Secrets to Designing an Effective UserDTO in Spring Boot Applications

Reasons You’re Not Receiving JWT Tokens and How to Fix It in Spring Security

Anh Trần Tuấn — Sat, 02 Aug 2025 09:00:01 +0000

1. Understanding Why JWT Tokens Are Not Received

JWT issues can arise at several stages of the token lifecycle: generation, delivery, or validation. Let’s break these down.

1.1 Misconfigured Security Filters

Spring Security relies heavily on filters to handle authentication. If your custom JWT filter isn’t properly registered or configured, Spring Security might bypass it entirely, preventing token generation or validation.

Example : Missing OncePerRequestFilter in your Spring Security configuration.

public class JwtAuthenticationFilter extends OncePerRequestFilter {
    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain filterChain) throws ServletException, IOException {
        String token = request.getHeader("Authorization");

        if (token == null || !token.startsWith("Bearer ")) {
            filterChain.doFilter(request, response);
            return;
        }

        // Proceed to validate and authenticate the token
        // Token validation logic here
    }
}

If you forget to add this filter in your security configuration, the token will never be processed:

@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.addFilterBefore(new JwtAuthenticationFilter(), UsernamePasswordAuthenticationFilter.class);
    }
}

1.2 Missing or Incorrect Authorization Header

The Authorization header in HTTP requests carries the JWT. If the client forgets to include this header or formats it incorrectly, the server will not receive the token.

Common Mistake : Sending a raw token without the Bearer prefix.

Authorization: Bearer <your-jwt-token>

If the header is sent as Authorization:
(without Bearer), the filter will fail to parse it. Modify the filter to include validation for the prefix:

if (!token.startsWith("Bearer ")) {
    response.sendError(HttpServletResponse.SC_UNAUTHORIZED, "Invalid Authorization header");
    return;
}

1.3 Expired or Invalid Token

Tokens have a limited lifespan defined during their generation. An expired token will fail validation, resulting in 401 Unauthorized responses.

Code Example: Token Generation with Expiration

public String generateToken(String username) {
    return Jwts.builder()
            .setSubject(username)
            .setIssuedAt(new Date())
            .setExpiration(new Date(System.currentTimeMillis() + 3600000)) // Token valid for 1 hour
            .signWith(SignatureAlgorithm.HS512, SECRET_KEY)
            .compact();
}

Solution : Ensure the token hasn’t expired before making requests. Additionally, verify the client’s system clock if you’re facing unexpected expiration issues.

1.4 Incorrect Secret Key or Algorithm Mismatch

The JWT is signed with a secret key using a specific algorithm. Any mismatch between the server’s and client’s key or algorithm can lead to validation failures.

Example of Algorithm Mismatch:

// Signing the token with HS256
.signWith(SignatureAlgorithm.HS256, SECRET_KEY)

If the client attempts to validate with a different algorithm (e.g., HS512), the server will reject the token.

2. Fixing JWT Issues in Spring Security

Once the root cause is identified, you can implement solutions to resolve the issues effectively.

2.1 Registering Custom Filters Correctly

Make sure your JWT authentication filter is added in the correct order in the Spring Security filter chain.

@Override
protected void configure(HttpSecurity http) throws Exception {
    http.csrf().disable()
        .authorizeRequests()
        .antMatchers("/api/auth/**").permitAll()
        .anyRequest().authenticated()
        .and()
        .addFilterBefore(new JwtAuthenticationFilter(), UsernamePasswordAuthenticationFilter.class);
}

2.2 Validating Tokens Properly

Use utility methods to validate the token’s structure, expiration, and signature.

Code Example: Token Validation

public boolean validateToken(String token) {
    try {
        Jwts.parser().setSigningKey(SECRET_KEY).parseClaimsJws(token);
        return true;
    } catch (ExpiredJwtException e) {
        System.out.println("Token has expired: " + e.getMessage());
    } catch (UnsupportedJwtException | MalformedJwtException | IllegalArgumentException e) {
        System.out.println("Invalid token: " + e.getMessage());
    }
    return false;
}

Ensure the filter uses this method:

String jwt = token.substring(7); // Remove "Bearer " prefix
if (!validateToken(jwt)) {
    response.sendError(HttpServletResponse.SC_UNAUTHORIZED, "Invalid or expired token");
    return;
}

2.3 Adding CORS Support

Cross-Origin Resource Sharing (CORS) can block tokens sent via browser-based requests if the CORS configuration is missing.

Code Example: Global CORS Configuration

@Bean
public WebMvcConfigurer corsConfigurer() {
    return new WebMvcConfigurer() {
        @Override
        public void addCorsMappings(CorsRegistry registry) {
            registry.addMapping("/**")
                    .allowedOrigins("http://localhost:3000")
                    .allowedMethods("GET", "POST", "PUT", "DELETE")
                    .allowCredentials(true);
        }
    };
}

2.4 Debugging Tips for Missing Tokens

Enable Logs : Use Spring Security debugging to trace request and filter execution.

logging.level.org.springframework.security=DEBUG

Check Request Headers : Use tools like Postman or curl to ensure headers are being sent correctly.

Validate Secret Keys : Confirm the secret key is consistent across environments.

3. Conclusion

JWT integration with Spring Security is straightforward when properly configured. However, minor missteps in filters, headers, or token validation can lead to frustrating issues. By following the steps outlined above—such as registering filters, handling headers correctly, and configuring token validation—you can ensure a robust JWT authentication system.

Do you have any lingering questions or challenges related to JWT implementation in Spring Security? Let’s discuss them in the comments below!

Read posts more at : Reasons You’re Not Receiving JWT Tokens and How to Fix It in Spring Security

DTO and Entity Separation is Crucial for Java Backend Applications

Anh Trần Tuấn — Fri, 01 Aug 2025 09:00:40 +0000

1. What are DTOs and Entities?

Before exploring their nuances, it is crucial to define these two terms.

1.1 Entities: The Foundation of Persistence

Entities represent the database table mappings in Java applications. Annotated with @Entity, these objects contain fields that correspond to columns in a database table. They are typically used in JPA/Hibernate to handle database operations.

@Entity
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String name;
    private String email;

    // Getters and Setters
}

Here, the User entity maps directly to a table in the database, making it tightly coupled to the database schema.

1.2 DTOs: Simplifying Data Communication

DTOs, on the other hand, are plain Java objects (POJOs) designed to transfer data between different layers of an application. They focus solely on carrying data, often in a more lightweight format than entities.

public class UserDTO {
    private String name;
    private String email;

    // Getters and Setters
}

In this example, UserDTO omits database-specific annotations and fields, focusing only on the information required by the client.

1.3 The Key Difference

The primary distinction lies in their purpose:

Entities are database-centric and used for persistence operations.
DTOs are client-centric and used for communication between application layers.

2. Why Separate DTOs and Entities?

While combining DTOs and Entities might seem convenient, it introduces significant challenges that can snowball over time.

2.1 Tight Coupling and Schema Changes

Entities are tightly coupled to the database schema. If a database schema changes, the corresponding entity must also change. Using entities directly as DTOs means any schema change can cascade into breaking API changes.

// Entity directly exposed as API response
@Entity
public class Product {
    @Id
    private Long id;
    private String name;
    private double price;
    private String internalCode; // Newly added field
}

Adding internalCode to the Product entity inadvertently exposes sensitive data if used directly in API responses. A DTO could have prevented this.

2.2 Overfetching and Underfetching Data

Entities often contain fields irrelevant to client requests. When used directly, they can lead to overfetching (sending unnecessary data) or underfetching (not providing required fields).

public class ProductDTO {
    private String name;
    private double price;

    // Constructor, Getters, and Setters
}

Here, ProductDTO ensures only relevant fields are included, improving performance and security.

2.3 Improved Validation and Transformation

DTOs allow for specific validation logic and data transformation tailored to client needs, reducing complexity in entities.

3. How to Work with DTOs and Entities

Mapping Between DTOs and Entities

One of the key tasks is converting between DTOs and Entities. This can be done manually or using libraries like MapStruct or ModelMapper.

public class UserMapper {
    public static UserDTO toDTO(User user) {
        UserDTO dto = new UserDTO();
        dto.setName(user.getName());
        dto.setEmail(user.getEmail());
        return dto;
    }

    public static User toEntity(UserDTO dto) {
        User user = new User();
        user.setName(dto.getName());
        user.setEmail(dto.getEmail());
        return user;
    }
}

3.2 Using MapStruct for Efficiency

MapStruct automates the mapping process with annotations:

@Mapper
public interface UserMapper {
    UserDTO toDTO(User user);
    User toEntity(UserDTO dto);
}

Using MapStruct eliminates boilerplate code while ensuring accuracy.

3.3 Layering for Clear Separation

Architectural layering further enforces separation:

Controller Layer : Accepts DTOs as input and sends DTOs as output.
Service Layer : Handles business logic and mapping between DTOs and Entities.
Repository Layer : Operates directly on Entities for database interactions.

4. Best Practices for DTOs and Entities

Avoid Bi-directional Mapping

A common mistake is embedding one object type in another, creating circular dependencies.

public class OrderDTO {
    private UserDTO user; // Can lead to circular references
}

Instead, use identifiers or simplified objects to represent relationships.

Keep DTOs Lean

Include only the necessary fields in DTOs to minimize payload size and improve performance.

Separate Input and Output DTOs

Use distinct DTOs for incoming requests and outgoing responses to better align with API requirements.

public class UserRequestDTO {
    private String name;
    private String email;
}
public class UserResponseDTO {
    private Long id;
    private String name;
    private String email;
}

5. Common Errors and Troubleshooting

Performance Issues with Mapping

Overusing manual mapping can degrade performance in large applications. Optimize by adopting automated mapping tools.

Validation Conflicts

Ensure validations are applied consistently across layers. Use DTOs for input validation and entities for database constraints.

6. Conclusion

In Java backend applications, properly handling DTOs and Entities is essential for maintaining a scalable and maintainable architecture. By separating these two concepts, developers can avoid tight coupling, enhance performance, and ensure robust validation. Have you faced challenges when working with DTOs and Entities? Share your experiences or questions in the comments below!

Read posts more at : DTO and Entity Separation is Crucial for Java Backend Applications