DEV Community: Àlámú

Angular Components: Composition-Driven Forms Over Inheritance

Àlámú — Sun, 13 Apr 2025 12:30:52 +0000

Angular Components: Composition-Driven Forms Over Inheritance
In Object-Oriented Programming (OOP), Composition (Has-A) is a key concept, alongside Inheritance (Is-A).

In Angular, we often use composition naturally when we inject services into components - services that handle API requests, caching, etc.

However, inheritance - extending a BaseComponent - is also common in Angular. One of the main strengths of Inheritance is shared behavior.

It works well in many cases, but sometimes it creates a subtle problem:

When the base component starts holding form-related logic, it forces every child component (even those that only display data, not create or update data) to inherit logic that they might not need. This can lead to tightly-coupled components.

Keeping the base component simple and minimal is a valid OOP approach.

For example, a BaseComponent might look like this:

// src/app/shared/component/base.component.ts

@Component({
  selector: '',
  template: '',
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class BaseComponent {

  private errorMsg: WritableSignal<string> = signal('');
  private statusMsg: WritableSignal<string> = signal('');
  private ready: WritableSignal<boolean> = signal(false);

  protected componentReady(): void {
    this.ready.set(true);
  }

  protected resetErrorMessage(): void {
    this.errorMsg.set('');
  }

  protected resetStatusMessage(): void {
    this.statusMsg.set('');
  }

  protected updateStatusMessage(message: string = ''): void {
    this.statusMsg.set(message);
  }

  protected updateErrorMessage(message: string = ''): void {
    this.errorMsg.set(message);
  }

  public get isComponentReady(): boolean {
    return this.ready();
  }

  public get errorMessage(): string {
    return this.errorMsg();
  }

  public get statusMessage(): string {
    return this.statusMsg();
  }
}

Reusing logic through inheritance like this is perfectly fine - when done carefully.

However, when it comes to handling forms, a cleaner and more scalable approach is to compose form functionality inside components, rather than inheriting it.

In this guide, we'll see how to:

Create a domain model (ChatRoom)
Build a reusable form (ChatRoomForm)
Define a component interface (HasForm similar to OnInit)
Create a BaseForm class that can be extended by form-related classes.

Section 1: Creating ChatRoom

Let's define a simple domain model for creating or updating a chat room.

// src/app/model/domain/chat-room.ts

export class ChatRoom {
  public readonly id: number | string;
  public readonly title: string;
  public readonly description: string;
  public readonly tags: string;
  public readonly guidelinesOrRules: string;
  public readonly visibility: ChatRoomVisibility;

  public constructor(data: ChatRoom) {
    this.id = data.id ?? undefined;
    this.title = data.title ?? '';
    this.description = data.description ?? '';
    this.tags = data.tags ?? '';
    this.guidelinesOrRules = data.guidelinesOrRules ?? '';
    this.visibility = data.visibility ?? '';
  }

  public static of(data: ChatRoom): ChatRoom {
    return new ChatRoom(data);
  }

  public static empty(): ChatRoom {
    return new ChatRoom({} as ChatRoom);
  }
}

Section 2: CreatingBaseForm

Now, let's define the base form as follows:

// src/app/model/form/base.form.ts

export abstract class BaseForm<T> {

  protected formGroup!: FormGroup;

  private submitting: WritableSignal<boolean> = signal(false);
  private formReady: WritableSignal<boolean> = signal(false);
  private formCompleted: WritableSignal<boolean> = signal(false);

  protected constructor() {}

  protected initForm(): void {}

  protected control(name: string): AbstractControl | null | undefined {
    return this.form?.get(name);
  }

  public enableFormComplete(): void {
    this.formCompleted.set(true);
  }

  public disableFormCompleted(): void {
    this.formCompleted.set(false);
  }

  public openForm(): void {
    this.formReady.set(true);
  }

  public startSubmitting(): void {
    this.submitting.set(true);
  }

  public stopSubmitting(): void {
    this.submitting.set(false);
  }

  public get form(): FormGroup {
    return this.formGroup;
  }

  public get value(): T {
    return this.form.value as T;
  }

  public get isFormValid(): boolean {
    return this.formGroup.valid;
  }

  public get isFormCompleted(): boolean {
    return this.formCompleted();
  }

  public get isFormReady(): boolean {
    return this.formReady();
  }

  public get isSubmitting(): boolean {
    return this.submitting();
  }

  public get isNotSubmitting(): boolean {
    return !(this.isSubmitting);
  }

}

The formGroup contains your form.

The submitting signal tracks your form's submission state. You can use it to prevent multiple submissions until the request is processed.

The formReady signal helps you display the HTML form in the UI when initialization of the form with its control and data is completed.

The formCompleted signal is optional. It helps you display UI animations or transitions as feedback when the form submission is complete.

The control method allows you to easily retrieve a form control from a form group without repetition of syntax. For example:

  public get title(): AbstractControl | null | undefined {
    return this.control('title');
  }

  public get description(): AbstractControl | null | undefined {
    return this.control('description');
  }

is simple compared to

  public get title(): AbstractControl | null | undefined {
    return this.formGroup?.get('title');
  }

  public get description(): AbstractControl | null | undefined {
    return this.formGroup?.get('description');
  }

The form's variable name might change, but using the control method provides a single source of truth and the logic for retrieving a form control is encapsulated. When there is a change, you update only this method.

The getter and other methods are a way of encapsulating the logic and behavior of the form and also giving you access to its state and data.

Section 3: CreatingChatRoomForm

Now, we will create ChatRoomForm

// src/app/model/form/chat-room.form.ts

export class ChatRoomForm extends BaseForm<CreateChatRoomPayload> {

  private constructor(
      private formBuilder: FormBuilder,
      private chatRoom: ChatRoom) {
    super();
  }

  public get title(): AbstractControl | null | undefined {
    return this.control('title');
  }

  public get description(): AbstractControl | null | undefined {
    return this.control('description');
  }

  public get guidelines(): AbstractControl | null | undefined {
    return this.control('guidelinesOrRules');
  }

  public get tags(): AbstractControl | null | undefined {
    return this.control('tags');
  }

  public get visibility(): AbstractControl | null | undefined {
    return this.control('visibility');
  }

  public get visibilities(): string[] {
    return Object.values(ChatRoomVisibility);
  }

  protected override initForm(): void {
    this.formGroup = this.formBuilder.group({
      title: [this.chatRoom.title, [
        required,
        minLength(10),
        maxLength(500),
      ]],

      description: [this.chatRoom.description, [
        required,
        maxLength(1000),
      ]],

      tags: [this.chatRoom.tags, [
        required,
        minLength(10),
        maxLength(500),
      ]],

      guidelinesOrRules: [this.chatRoom.guidelinesOrRules, [
        required,
        maxLength(1500),
      ]],

      visibility: [this.chatRoom.visibility, [
        required,
        oneOf(ChatRoomVisibility)
      ]],

    });
  }

  public static of(formBuilder: FormBuilder, chatRoom: ChatRoom): ChatRoomForm {
    const chatRoomForm: ChatRoomForm = new ChatRoomForm(formBuilder, chatRoom);
    chatRoomForm.initForm();

    return chatRoomForm;
  }

  public static empty(formBuilder: FormBuilder): ChatRoomForm {
    return new ChatRoomForm(formBuilder, ChatRoom.empty());
  }
}

The ChatRoomForm has a private constructor since it's not used in dependency injection. Instead, it's created via the static of method, following the factory pattern.

Using validators this way reduces repetition of the Validators class and supports polymorphic implementations. You can introduce custom validators, and changes apply instantly without updating the entire codebase. For example, you can define validators like this:

// src/app/shared/validators/index.ts

export const required = Validators.required;
export const minLength = Validators.minLength;
export const maxLength = Validators.maxLength;

Learn more about How to Organize Validators in an Angular app.

Section 4: Creating HasForm Interface

The HasForm interface, for components requiring a user-filled form, looks like this:

// src/app/model/interface/form/has-form.interface.ts

export interface HasForm {

  formReady(): void;

  initForm(data?: any): void;

  startSubmitting(): void;

  stopSubmitting(): void;

  completeForm(): void;

  get formModel(): BaseForm<any>;

  get payload(): any;

  get isFormReady(): boolean;

  get isFormCompleted(): boolean;

  get isFormValid(): boolean

  get isNotSubmitting(): boolean;

  get isSubmitting(): boolean;
}

These getter methods encapsulate the actual form behavior and logic and will be used in the UI and some part of your component.

These behaviors were usually implemented in the BaseComponent before and then inherited by extending components. This isn't always ideal as components like ChatRoomItem and ChatRoomList typically display data without mutating or updating it.

You can adapt this interface to work with your existing component design patterns and architecture.

The CreateChatRoom component looks like

@Component({
  selector: 'app-create-chat-room',
  imports: [
    ValidationErrorComponent,
    ReactiveFormsModule,
    FaIconComponent,
  ],
  providers: [
    ChatRoomService,
  ],
  templateUrl: './create-chat-room.html',
  styleUrl: './create-chat-room.css'
})
export class CreateChatRoom extends BaseComponent implements OnInit, HasForm {

  protected readonly chatRoomService: ChatRoomService = inject(ChatRoomService);
  protected readonly formBuilder: FormBuilder = inject(FormBuilder);

  protected readonly chatRoomForm: WritableSignal<ChatRoomForm> = signal(ChatRoomForm.empty(this.formBuilder));

  public ngOnInit(): void {
    this.initForm();
  }

  public formReady(): void {
    this.formModel.openForm();
    this.componentReady();
  }

  public completeForm(): void {
    this.formModel.completeForm();
  }

  public initForm(): void {
    const createChatRoomForm: ChatRoomForm = ChatRoomForm.of(this.formBuilder, ChatRoom.empty());
    this.chatRoomForm.set(createChatRoomForm);

    this.formReady();
  }

  public createChatRoom(): void {
    if (this.isFormValid && this.isNotSubmitting) {
      this.startSubmitting();

      const payload: CreateChatRoomPayload = this.payload;
      this.chatRoomService.create(payload)
        .subscribe({
          next: (response: CreateChatRoomResponse): void => { this.createChatRoomSuccess(response); },
          error: (error: ErrorResponse): void => { this.createChatRoomFailure(error); },
          complete: (): void => { this.createChatRoomComplete(); }
      });
    }
  }

  protected createChatRoomSuccess(result: CreateChatRoomResponse): void {
    this.updateStatusMessage(result.message);
  }

  protected createChatRoomFailure(error: ErrorResponse): void {
    this.updateErrorMessage(error.message);
    this.createChatRoomComplete();
  }

  protected createChatRoomComplete(): void {
    this.stopSubmitting();
    this.completeForm();
  }

  public startSubmitting(): void {
    this.formModel.startSubmitting();
  }

  public stopSubmitting(): void {
    this.formModel.stopSubmitting();
  }

  public get createChatRoomForm(): FormGroup {
    return this.formModel.form;
  }

  public get payload(): CreateChatRoomPayload {
    return this.formModel.value;
  }

  public get formModel(): ChatRoomForm {
    return this.chatRoomForm();
  }

  public get isFormReady(): boolean {
    return this.formModel.isFormReady;
  }

  public get isFormValid(): boolean {
    return this.formModel.isFormValid;
  }

  public get isFormCompleted(): boolean {
    return this.formModel.isFormCompleted;
  }

  public get isSubmitting(): boolean {
    return this.formModel.isSubmitting;
  }

  public get isNotSubmitting(): boolean {
    return this.formModel.isNotSubmitting;
  }

  protected readonly faCheck = faCheck;
  protected readonly faSpinner = faSpinner;
  protected readonly faPlus = faPlus;
}

The signal(ChatRoomForm.empty()) initialize the signal with a form but whose state would not be ready, the UI and code is guarded and protected with the isFormReady check in the HTML template.

@if (isFormReady) {
  <!-- .....HTML Form .......-->
}

The initForm method creates a new ChatRoomForm using static of method, initialize the form with opens the form and ready to be interacted with and then return it.

The openForm method sets the formReady signal state to true which indicates initialization is complete and the form is ready to be interacted with or completed by the user.

The payload getter method returns the form value you will use to create the chat room. Its type looks like this

export type CreateChatRoomPayload = {
  title: string;
  description: string;
  guidelinesOrRules: string;
  tags: string;
  visibility: ChatRoomVisibility | string;
}

The payload getter method allows you to preprocess or add other details before the data is used. For example

public get payload(): CreateLiveStreamPayload {
  const data: CreateLiveStreamPayload = this.formModel.value;
  return {
    ...data,
    startDateTime: addSecondsToDate(this.formModel.startDateTimeValue),
    endDateTime: addSecondsToDate(this.formModel.endDateTimeValue),
  };
}

Section 5: HTML Template

@if (isComponentReady && isFormReady) {
  <form name="create-chat-room" method="post" enctype="application/x-www-form-urlencoded" autocomplete="off" [formGroup]="createChatRoomForm" (ngSubmit)="createChatRoom()">
    <div>
      <label for="title">Title*:</label>
      <input type="text" id="title" name="title" formControlName="title" autocomplete="off"/>
      <validation-error label="Title" [field]="formModel.title"></validation-error>
    </div>

    <div>
      <label for="description">Description*:</label>
      <input type="text" id="description" name="description" formControlName="description" autocomplete="off"/>
      <validation-error label="Description" [field]="formModel.description"></validation-error>
    </div>

    <!-- Other HTML markup removed for brevity. -->

    <button type="submit" [disabled]="isSubmitting">Create

      @if (isFormCompleted) {<fa-icon [icon]="faCheck"/>}
      @else if (isSubmitting) {<fa-icon [icon]="faSpinner" [animation]="'spin'"/>}
      @else if (isNotSubmitting) {<fa-icon [icon]="faPlus"/>}
    </button>
  </form>
}

You use the getter methods to enhance the UI and form logic.

Addition:

What about the completeForm()?

Earlier, I mentioned how the formCompleted signal aids UI animations. The implementation is as follows:

  protected formCompleted: WritableSignal<boolean> = signal(false);

The implementation in the BaseForm will look something like this:

  public completeForm(delayToReset: number = 5000): void {
    // Ensure delay is non-negative
    const safeDelay: number = Math.max(0, delayToReset);

    // Mark the form as completed
    this.enableFormComplete();

    // Set a timer to reset form completion status
    timer(safeDelay).pipe(
      // Reset form completion status
      tap(() => this.disableFormCompleted()),
    ).subscribe();
  }

When the user's form submission is completed and the completeForm() is called, the Font Awesome animation starts as indicated here

@if (isFormCompleted) {<fa-icon [icon]="faCheck"/>}

After the 5 seconds default delay, the status is reset to false and the check or mark icon disappears.

Note:

Of course, the methods in HasForm have already been defined in the formModel or BaseForm. It's debatable whether this introduces over-abstraction. You can decide to implement all the methods in HasForm or you can remove some and access the formModel in the Component code or directly in the HTML template.

Repository: Angular Form Composition

Using composition leads to better separation of concerns, easier testing, and more reusable components. I hope you enjoy it.

A Guide to Localizing and Internationalizing Your Java App with Localizer

Àlámú — Sun, 02 Feb 2025 17:09:42 +0000

This guide is about Java and I'll show you how to localize your app using Localizer.

Localization and i18n should be simple, which is why I created Localizer.

How the Idea for Localizer Came About

In my free time, I'm developing a social networking app and I realized that I need to make the app i18n-compatible.

I decided to create an API. I then open sites like Facebook and others to observe how their API responses are localized, and it was done in a fashion similar to the way I do it.

In my opinion, handling localized responses from the server or backend would be easy to change and maintain going forward because the API can be consumed by web, mobile, and desktop devices, etc. Single sources of truth are awesome.

So I am open-sourcing Localizer.

Localizer is a Java library that simplifies internationalization for your Java applications, allowing them to support multiple languages with ease.

It allows seamless resolution of localized messages usingLocalizer instances or beans, supporting multiple locales for general, response, and error messages. It integrates with Spring, and other frameworks, such as Vaadin, Quarkus, and Jakarta.

So let's get on with how to localize your application's APIs and backend responses.

The code examples are going to be based on Spring Boot.

Setting Up Localizer

Step 1: How to download & install dependency

To add Localizer, include the following dependency in your pom.xml file.

<dependency>
   <groupId>com.fleencorp.i18n</groupId>
   <artifactId>localizer</artifactId>
   <version>2.0.6</version>
  </dependency>

If you're using Gradle, include the following in your build.gradle file:

implementation 'com.fleencorp.i18n:localizer:2.0.6'

Step 2: How to Configure the Message Source and Localizer

Now, let's create a @Configuration class to define the message source:

You can create it in a package of your choice, for example, com.fleencorp.travelstar. I will name mine MesssageSourceConfiguration

@Configuration
public class MessageSourceConfiguration {}

You can specify the paths to your message source files directly in your configuration class or externalize them to the application.properties file. For example:

spring.messages.encoding=UTF-8
spring.messages.message.base-name=classpath:i18n/messages
spring.messages.error.base-name=classpath:i18n/errors/messages

Note: The /messages part is not a directory or folder but rather a filename pattern that allows Spring to find the message source files and their locale-specific ones like messages_en_US.properties, messages_de.properties, messages_fr.properties, and so on. It looks something like this:

Step 3: How to populate the Configuration class

@Configuration
public class MessageSourceConfiguration {

  @Value("${spring.messages.encoding}")
  private String messageSourceEncoding;

  @Value("${spring.messages.message.base-name}")
  private String messageBaseName;

  @Value("${spring.messages.error.base-name}")
  private String errorMessageBaseName;

  private ReloadableResourceBundleMessageSource baseMessageSource() {
    final ReloadableResourceBundleMessageSource messageSource = new ReloadableResourceBundleMessageSource();
    messageSource.setCacheSeconds(60);
    messageSource.setDefaultLocale(Locale.US);
    messageSource.setAlwaysUseMessageFormat(true);
    messageSource.setUseCodeAsDefaultMessage(false);
    messageSource.setFallbackToSystemLocale(false);
    messageSource.setDefaultEncoding(messageSourceEncoding);
    return messageSource;
  }

  private MessageSource messageSource() {
    final ReloadableResourceBundleMessageSource messageSource = baseMessageSource();
    messageSource.setBasenames(messageBaseName);
    return messageSource;
  }

  private MessageSource errorMessageSource() {
    final ReloadableResourceBundleMessageSource messageSource = baseMessageSource();
    messageSource.setBasenames(errorMessageBaseName);
    return messageSource;
  }

  @Bean
  public Localizer localizer() {
    return new LocalizerAdapter(messageSource());
  }

  @Bean
  public ErrorLocalizer errorLocalizer() {
    return new ErrorLocalizerAdapter(errorMessageSource());
  }
}

Questions:

Question 1: What can I change?

You can configure ReloadableResourceBundleMessageSource according to your preference if you wish. You can also replace it with a message source bundle like ResourceBundleMessageSource.

Question 2: What are some simple and effective naming patterns for message keys?

You can do it in a way that aligns with the existing standard you are working with. In my case, I name message keys based on the response or exception class name without the suffix. I also group response and error messages alphabetically and based on their similarities. For example:

public class MfaStatusResponse {}
public class ResendMfaVerificationCodeResponse {}
public class StartSetupMfaResponse {}

public class AlreadySignedUpException {}
public class DisabledAccountException {}
public class UsernameNotFoundException {}

# Responses
# Mfa
mfa.status=Mfa status retrieved successfully
resend.mfa.verification.code=Verification code sent successfully
start.setup.mfa=Mfa setup in progress

# Errors
# Auth
already.signed.up=This profile is already signed up and has completed the registration process.
disabled.account=This account has been disabled.
username.not.found=The username or password is invalid. ID: {0}.

Question 3: Why do we need two MessageSource?

To make maintainability and change easier. Having separate message sources will make your life easier as your application localization need grows.

I even have three message sources, as shown in the screenshot above: one for the usual API responses, one for the error responses and another for general use, like notification message keys and other simple classes like the below:

public class MfaTypeInfo {

  private MfaType mfaType; // MfaType is an enum that has message codes
  private String mfaTypeText;
}

public class ProfileStatusInfo {

  private ProfileStatus status; // ProfileStatus is an enum that has message codes
  private String profileStatusText;
}

# Mfa Type
mfa.type.phone=Phone
mfa.type.email=Email
mfa.type.authenticator=Authenticator
mfa.type.none=None

# Profile Status
profile.status.active=Active
profile.status.banned=Banned

The above is all the configurations or settings you need. It's that simple.

While working on Localizer, I also explored Hexagonal Architecture when my lead talked about it. The approach solidified my opinion in separating concerns - making localization simple and easily integrated into the business logic.

Another benefit is that it makes testing easier and it reduces the tight coupling between your service classes and other dependencies. I also went the extra mile by replacing external service classes in the app core logic with their equivalent contracts and interfaces.

The concept is beneficial. I like it, so I decided to refactor anything I consider to be a potential technical debt in the future.

To maintain a clean application core and business logic, localization details will be moved to DTOs, responses, and other simple model classes.

I won't be satisfied if the ApiResponse, which is intended solely for i18n and localization, is scattered throughout the application's core implementations.

How to Configure a DTO for a Localized Response

To configure a DTO for localized responses, you can extend the ApiResponse class. For example:

public class RetrieveCountryResponse extends ApiResponse {

  @Override
  public String getMessageCode() {
    return "retrieve.country";
  }
}

It's as simple as extending the ApiResponse class.

The message would look like this:

# messages_fr.properties
# Country
retrieve.country=Country retrieved successfully

# messages_fr.properties
# Country
retrieve.country=Pays récupéré avec succès

In the code I write, it looks like this:

@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class RetrieveCountryResponse extends ApiResponse {

  @JsonProperty("country")
  private CountryResponse country;

  @Override
  public String getMessageCode() {
    return "retrieve.country";
  }

  public static RetrieveCountryResponse of(final CountryResponse country) {
    return new RetrieveCountryResponse(country);
  }
}

Here's how to localize RetrieveCountryResponse before returning the HTTP response to the requester or consumer of the API.

The service that returns the response looks like this

public interface CountryService {

  RetrieveCountryResponse getCountry(Long countryId);
}

The implementation looks like

@Service
public class CountryServiceImpl implements CountryService {

  private final CountryRepository countryRepository;
  private final Localizer localizer;

  public CountryServiceImpl(
      final CountryRepository countryRepository,
      final Localizer localizer) {
    this.countryRepository = countryRepository;
    this.localizer = localizer;
  }

  @Override
  public RetrieveCountryResponse getCountry(final Long countryId) {
    final Country country = countryRepository.findById(countryId)
            .orElseThrow(CountryNotFoundException.of(countryId));

    final CountryResponse countryResponse = CountryMapper.toCountryResponse(country);
    final RetrieveCountryResponse retrieveCountryResponse = RetrieveCountryResponse.of(countryResponse);

    return localizer.of(retrieveCountryResponse);
  }

}

The cool thing about the pattern above is that it promotes loose coupling, which I'm happy with. There are no external details in your core logic, other than the localizer. In the controller, it would look like this:

  @GetMapping(value = "/detail/{countryId}")
  public RetrieveCountryResponse getCountry(
      @PathVariable(name = "countryId") final Long countryId) {
    return countryService.getCountry(countryId);
  }

Your response would look like this:

{
    "message": "Country retrieved successfully",
    "country": {
        "id": 60,
        "title": "Finland",
        "code": "FIN",
        "timezone": "Europe/Helsinki",
        "created_on": "2024-10-03T21:52:14",
        "updated_on": "2024-10-03T21:52:14"
    }
}

Don't mind me 🙂, I like snake_case for my fields, but I transform them to camelCase on the frontend.

Other examples of localized response include;

@AllArgsConstructor
public class BlockUserStatusResponse extends ApiResponse {

  private BlockStatus blockStatus;

  @Override
  public String getMessageCode() {
    return BlockStatus.isBlocked(blockStatus)
      ? "block.user.status.blocked"
      : "block.user.status.unblocked";
  }

  public static BlockUserStatusResponse of(final BlockStatus blockStatus) {
    return new BlockUserStatusResponse(blockStatus);
  }
}

The messages would look like

# messages.properties 
block.user.status.blocked=You blocked this user
block.user.status.unblocked=Unblock this user

# messages_fr.properties
block.user.status.blocked=Vous avez bloqué cet utilisateur
block.user.status.unblocked=Débloquer cet utilisateur

Your API response can contain parameters too like

public class ContactRequestResponse extends ApiResponse {

  private String requesterUsername;

  @Override
  public String getMessageCode() {
    return "contact.request";
  }

  @Override
  public Object[] getParams() {
    new Object[] { requesterUsername };
  }
}

The messages might look like

# messages.properties 
contact.request={0} wants to be your friend

# messages_fr.properties
contact.request={0} veut être votre ami

Parameters are handled based on their index or position in the array. {0} for the first element, {1} for the second element, {2} for the third element and so on

That's all about localizing your API responses!

How to localize your Error response

public class DisabledAccountException extends ApiException {

  @Override
  public String getMessageCode() {
    return "disabled.account";
  }
}

In a service, it might look something like this;

if (ProfileStatus.isDisabled(profileStatus)) {
  throw new DisabledAccountException();
}

You will create an exception handler and use RestControllerAdvise if the response is REST API-based like this

@RestControllerAdvice
public class GlobalExceptionHandler {

  private final ErrorLocalizer localizer;

  public GlobalExceptionHandler(final ErrorLocalizer localizer) {
    this.localizer = localizer;
  }

  @ExceptionHandler(value = {
    DisabledAccountException.class,
  })
  @ResponseStatus(value = BAD_REQUEST)
  public ErrorResponse handleBadRequest(final ApiException e) {
    return localizer.withStatus(e, Response.Status.BAD_REQUEST);
  }

}

The Response class is part of the Java Jakarta RESTful Web Services library.

ErrorResponse is a simple and awesome utility.

You don't necessarily have to return ErrorResponse if you prefer to create your own. For example:

@ExceptionHandler(value = {
  DisabledAccountException.class,
})
@ResponseStatus(value = BAD_REQUEST)
public YourOwnErrorResponse handleBadRequest(final ApiException ex) {
  final String message = localizer.getMessage(ex.getMessageCode());
  return new YourOwnErrorResponse(message);
}

And that's it for localizing error responses!

Let's also explore some advanced use of localizer

Here's an example of a SignInResponse I created:

public class SignInResponse extends ApiResponse {

  // ... Other fields not included
  private String accessToken;
  private String refreshToken;

  private AuthenticationStatus authenticationStatus;
  private MfaTypeInfo mfaTypeInfo;

  @Override
  public String getMessageCode() {
    return "sign.in";
  }

  @JsonIgnore
  public String getPreVerificationMessageCode() {
    return "sign.in.pre.verification";
  }

  @JsonIgnore
  public String getMfaAuthenticatorMessageCode() {
    return "sign.in.mfa.authenticator";
  }

  @JsonIgnore
  public String getMfaEmailOrPhoneMessageCode() {
    return MfaType.isEmail(getMfaType())
      ? "sign.in.mfa.email"
      : "sign.in.mfa.phone";
  }

  @JsonIgnore
  public MfaType getMfaType() {
    return nonNull(mfaTypeInfo)
      ? mfaTypeInfo.getMfaType()
      : null;
  }

  @JsonIgnore
  public String getMfaMessageCode() {
    return MfaType.isAuthenticator(getMfaType())
      ? getMfaAuthenticatorMessageCode()
      : getMfaEmailOrPhoneMessageCode();
  }

  @Override
  public Object[] getParams() {
    final String verificationType = MfaType.isPhone(getMfaType()) ? phoneNumber.toString() : emailAddress.toString();
    return new Object[]{verificationType};
  }
}

The message.properties file looks like

# messages.properties
sign.in=Sign-in successful
sign.in.pre.verification=Enter the code sent to email to complete the sign up
sign.in.mfa.authenticator=Use an authenticator code to complete the process
sign.in.mfa.email=Code has been sent to your email {0}
sign.in.mfa.phone=Code has been sent to your phone {0}

# messages_fr.properties
sign.in=Connexion réussie
sign.in.pre.verification=Entrez le code envoyé à votre email pour compléter l'inscription
sign.in.mfa.authenticator=Utilisez un code d'authentificateur pour compléter le processus
sign.in.mfa.email=Un code a été envoyé à votre email {0}
sign.in.mfa.phone=Un code a été envoyé à votre téléphone {0}

In the AuthenticationServiceImpl, It looks like this and depending on the current status of the user's profile, the message will be different.

public SignInResponse signIn(final SignInDto signInDto) {
    final String emailAddress = signInDto.getEmailAddress();
    final String password = signInDto.getPassword();

    final Authentication authentication = authenticateCredentials(emailAddress, password);
    final AuthorizedUser user = (AuthorizedUser) authentication.getPrincipal();

    validateProfileIsNotDisabledOrBanned(user.getProfileStatus());

    final SignInResponse signInResponse = createDefaultSignInResponse(user);

    if (isProfileInactiveAndUserYetToBeVerified(user)) {
      return processSignInForProfileYetToBeVerified(signInResponse, user);
    }

    if (isMfaEnabledAndMfaTypeSet(user)) {
      return processSignInForProfileWithMfaEnabled(signInResponse, user);
    }

    return processSignInForProfileThatIsVerified(signInResponse, user, authentication);
  }

  protected SignInResponse processSignInForProfileYetToBeVerified(final SignInResponse signInResponse, final AuthorizedUser user) {
    handleProfileYetToBeVerified(signInResponse, user);
    return localizer.of(signInResponse, signInResponse.getPreVerificationMessageCode());
  }

  protected SignInResponse processSignInForProfileWithMfaEnabled(final SignInResponse signInResponse, final AuthorizedUser user) {
    handleProfileWithMfaEnabled(signInResponse, user);
    return localizer.of(signInResponse, signInResponse.getMfaMessageCode());
  }

  protected SignInResponse processSignInForProfileThatIsVerified(final SignInResponse signInResponse, final AuthorizedUser user, final Authentication authentication) {
    handleProfileThatIsVerified(signInResponse, user, authentication);
    return localizer.of(signInResponse);
  }

I hope you found this helpful & Good luck 🤞.

The following resources also helped me in getting my library published on Maven Central. I want to say Thank you.

References