Package io.github.qubitpi.athena.config

Interface MessageFormatter

All Known Implementing Classes:
ErrorMessageFormat
public interface MessageFormatter
MessageFormatter provides shared functionality to provide formatted logging and messaging.

Webservice applications deals with unchecked exceptions frequently. The application catches the exception, logs a custom message, and send another custom user-face error message back to client (also often passed to downstream exceptions). It has been observed that common or similar log/error messages can be used across components of the application.

For example, a Webservice endpoint takes a user request, which has a parameter like people.age. The endpoint will reserve an exception message like "age must be positive" for use for the case when user asks a negative age. This message is essentially saying "some number has to be positive".

It is very likely that other parts of the system also need to make sure some number needs to be positive, such as number of connections in a connection pool config. DRY principle encourages us to deduplicate the similar message in these 2 situations.

To do that, we can have a message format like "%s has to be positive" and replace the "%s" with "age" or "num connections". getLoggingFormat() in this case returns "%s has to be positive" and the argument to format(Object...) will be "age" and "num connections", respectively.

MessageFormatter also gives you flexibility to customize the message content based on the reader of the message. In the example of people age above, the error message to Webservice client might be "age has to be positive", but in the server log, a message like "endpoint 'xyz' has an invalid request parameter 'people.age'" will be much more useful to an engineer. To support that, getMessageFormat() and format(Object...) will be used for message that is sent to the client, while getLoggingFormat() and logFormat(Object...) will be used for message for the logging.

A recommended implementation of MessageFormatter is enum such as the following: 

 
 public enum ErrorMessageFormat implements MessageFormatter {
     NEGATIVE_NUMBER("'%s' has to be positive", "Negative invalid value found at component '%s'"),
     ...
     ;

     private final String messageFormat;
     private final String loggingFormat;

     ErrorMessageFormat(String messageFormat, String loggingFormat) {
         this.messageFormat = messageFormat;
         this.loggingFormat = loggingFormat;
     }

     @Override
     public String getMessageFormat() {
         return messageFormat;
     }

     @Override
     public String getLoggingFormat() {
         return loggingFormat;
     }
 }

  • Method Summary

    Modifier and Type
    Method
    Description
    default @NotNull String
    format(Object... values)
    Formats a message for reporting to a user/client.
    @NotNull String
    getLoggingFormat()
    Returns the message format used for logging.
    @NotNull String
    getMessageFormat()
    Returns the message used for publishing out of the system, typically in error messages.
    default @NotNull String
    logFormat(Object... values)
    Formats a message for writing to the log.

  • Method Details

    • getMessageFormat

      @NotNull @NotNull String getMessageFormat()
      Returns the message used for publishing out of the system, typically in error messages.
      Returns:
      the format for a message

    • getLoggingFormat

      @NotNull @NotNull String getLoggingFormat()
      Returns the message format used for logging.
      Returns:
      the format for a log message

    • format

      @NotNull default @NotNull String format(Object... values)
      Formats a message for reporting to a user/client.
      Parameters:
      values - The values to populate the format string
      Returns:
      the use message

    • logFormat

      @NotNull default @NotNull String logFormat(Object... values)
      Formats a message for writing to the log.
      Parameters:
      values - The values to populate the format string
      Returns:
      the logging message