DEV Community: Reda Messoudi

Polymorphic deserialization with Jackson and no annotations

Reda Messoudi — Fri, 16 Oct 2020 15:58:37 +0000

Suppose I asked you to take a cup from the multiple choices in the header photo, certainly you'll ask which one to choose as there is many cups and you need something precise and maybe unique by cup to decide.

All the choices are cups, they share some common points (color, weight, ...) but maybe each one has something that the other cups don't have. This is polymorphism.

Full source code available here.

What's polymorphism ?

Polymorphism is the ability to have different implementations represented by a single interface or abstract class.

This post is about how to deserialize objects by their abstract. Same idea presented below can be used to serialize objects.

Let's consider the following abstraction :

Suppose you have an POST endpoint which supports creation of multiple objects by abstraction. Something like : you POST /players when PLAYER can be FootballPlayer, TennisPlayer or BasketPlayer.

@PostMapping(value = "/players", consumes = MediaType.APPLICATION_JSON_VALUE)
  ResponseEntity<?> createPlayer(@RequestBody Player player);

Problem

If we go directly invoking the /players endpoint, we'll face the InvalidDefinitionException as Jackson can't define to which class instance the PLAYER request body should be deserialized.

What's Jackson ?

As claimed by it's creators :

Jackson has been known as "the Java JSON library" or "the best JSON parser for Java". Or simply as "JSON for Java".

Simply, Jackson is a Java library to serialize and deserialize objects to/from JSON.

I'll use Spring Boot in this post but if you want to go without it, just grab the latest dependency of Jackson Databind on Maven Central.

<dependency>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-core</artifactId>
  <version>VERSION_HERE</version>
</dependency>

Deserialization

The deserialization part will have to determine which concrete class the JSON represents, and instantiate an instance of it.

Deserialization using annotation

Using annotation is probably the most used technique because of it's simplicity and time-saving, but sometimes it's impossible to go with it.

Some resources describe how it can be done, you can check here or here if you are curious.

Deserialization with no annotation

Not every project gives the possibility to add annotations on your domain classes.

Sometimes, your domain classes (Player, FootballPlayer, ...) are hidden behind an imported jar dependency and you can't access them for annotating

you are using DDD and hexagonal architecture where purists say :

No framework or libraries inside the domain

simply because of some technical constraints in your company/project.

First thing to do is to create a custom Jackson deserializer and implement the logic of deserialization.

To implement a custom deserializer, we need to create an implementation of StdDeserializer which is an abstract type and the base class for common Jackson deserializers.

public class PlayerDeserializer extends StdDeserializer<Player> {

  public PlayerDeserializer() {
    this(null);
  }

  public PlayerDeserializer(final Class<?> vc) {
    super(vc);
  }

  @Override
  public Player deserialize(JsonParser jsonParser, DeserializationContext deserializationContext)
      throws IOException {
    // TODO - implement deserialization logic here
    return null;
  }

Few lines above, we exposed our abstraction of Player. Let's create an enum to distinguish the different Player instances.

public enum SportType {

  FOOTBALL("FOOTBALL"),
  TENNIS("TENNIS"),
  BASKET("BASKET");

  private final String value;

  SportType(String value) {
    this.value = value;
  }

  @Override
  public String toString() {
    return String.valueOf(value);
  }

  public static SportType fromValue(String text) {
    for (SportType sportType : SportType.values()) {
      if (String.valueOf(sportType.value).equals(text)) {
        return sportType;
      }
    }
    return null;
  }

As now we defined our SportType enum, based on that we can implement in details our deserialize method. Here we can take the benefit of this sportType field inside our abstract class PLAYER.

@Override
  public Player deserialize(JsonParser jsonParser, DeserializationContext deserializationContext)
      throws IOException {

    final ObjectMapper mapper = (ObjectMapper) jsonParser.getCodec();
    final JsonNode playerNode = mapper.readTree(jsonParser);

    final SportType sportType = SportType.fromValue(playerNode.get("sportType").asText());
    switch (sportType) {
      case FOOTBALL:
        return mapper.treeToValue(playerNode, FootballPlayer.class);
      case TENNIS:
        return mapper.treeToValue(playerNode, TennisPlayer.class);
      default:
        log.warn("Unexpected Player type : {}", sportType.toString());
        throw new IllegalStateException("Unexpected Player type : " + sportType.toString());
    }
  }

The last step to do before going ready for deserialization is to indicate that our PlayerDeserializer is a part of Jackson serializers/deserializers. Two possibilities available here :

As we use Spring Boot, we can use the @JsonComponent which do the same behavior but with less lines of code.

Maybe you're asking why we have this annotation as the title indicates "FREE ANNOTATIONS"? .

@JsonComponent is a Spring Boot annotation and not a part of Jackson and it lives in our newly created deserializer.

Another question can be :

What if we don't have this kind of "type" in our abstract class (e.g sportType) ?

In this case, we can change a little bit our deserialize method to inspect fields of each PLAYER instance (looking for something unique by each instance).

  @Override
  public Player deserialize(JsonParser jsonParser, DeserializationContext deserializationContext)
      throws IOException {

    final ObjectMapper mapper = (ObjectMapper) jsonParser.getCodec();
    final JsonNode playerNode = mapper.readTree(jsonParser);

    final SportType sportType = SportType.fromValue(playerNode.get("sportType").asText());

    if (playerNode.has("position")) {
      return mapper.treeToValue(playerNode, FootballPlayer.class);
    }
    if (playerNode.has("atpPoints")) {
      return mapper.treeToValue(playerNode, TennisPlayer.class);
    }
    log.warn("Unexpected Player type : {}", sportType.toString());
    throw new IllegalStateException("Unexpected Player type : " + sportType.toString());
  }

Conclusion

In this post, we learned how to handle, in the same endpoint, variable requests (polymorphism) in Jackson by using custom deserializer and without polluting our domain classes with annotations and external libraries.

Resources

Source code : https://github.com/redamessoudi/polymorphic-deserialization

Header photo by Eric Prouzet on Unsplash

Receive emails with SubEtha SMTP and Spring Boot

Reda Messoudi — Mon, 13 Jul 2020 07:51:39 +0000

Some years ago I needed to write a Java application that receives emails and process some business stuff on those. It wasn't an easy task as I didn't find a lot of information. Because of that I decided, one day, I'll write about it and maybe that could helps 🙂.

Full source code available here.

Context

Why ?

You would ask why do you need that ? I would say :

Business requirements can surprise you every day

Below a small list of some use cases when this incoming emails processing can be helpful.

Testing : Can be good option for integration testing the email capabilities of your services/applications (The old FakeSMTP is a good GUI example)
Analyse received emails and extract some specific information
...

What ?

SubEtha SMTP is low-level API for writing almost any kind of SMTP mail-receiving application.

To avoid you a long history presentation, the most updated version of SubEtha SMTP is a fork by David Moten (many thanks to him for his excellent work and keeping this library updated). We'll use this fork in this post.

I think no need to describe what's Spring Boot in nowadays.

Let's code

Before starting the code, I suggest to see how we can send an email via terminal. We'll need that to send an email to our future emails receiver application.

Send email with cURL

Below an example of sending email to specific mail server with parameters like from, recipient, auth and the content of the email.

curl --url 'smtp://localhost:25000' \                                     
  --mail-from 'customer-address@mail.com' \
  --mail-rcpt 'info@marketing.company.com' \
  --user 'superus3r:passw0rd' \
  -T <(echo -e 'From: customer-address@mail.com\nTo: info@marketing.company.com\nSubject: cURL Test\n\nHello, this is the content')

SubEtha dependency

Here we add the maven dependency of SubEtha SMTP.

<dependency>
    <groupId>com.github.davidmoten</groupId>
    <artifactId>subethasmtp</artifactId>
    <version>5.2.4</version>
</dependency>

Start the embedded SMTP server

It's very easy to start a simple SMTP server with the library. Just create/build an instance of SMTPServer with the right parameters like port and start this instance.

// Build the embedded SMTP server
SMTPServer smtpServer = SMTPServer.port(25000).build();
// Start server asynchronously 
smtpServer.start();

Now our SMTP server is started but not fully ready to receive emails. We need to implement a MessageListener to extract important data like from and recipient addresses but also the subject and the body of the received email.

For that we can implement the SimpleMessageListener interface :

public class MarketingMailListener implements SimpleMessageListener {

    private static final String MARKETING_DOMAIN = "@marketing.company.com";

    /**
     * Do some business logic here
     */
    @Override
    public boolean accept(String from, String recipient) {
        return recipient != null && recipient.endsWith(MARKETING_DOMAIN);
    }

    @Override
    public void deliver(String from, String recipient, InputStream data) 
    throws TooMuchDataException, IOException {
        System.out.println("deliver message of MARKETING department");
        System.out.println("From : "+from);
        System.out.println("Recipient : "+recipient);
    }

As you can see here, I added a simple business rule inside accept method to handle only emails sent to marketing department.

The accept method is responsible for defining if the received message will be proceeded by this listener or not.

The deliver method is responsible for extracting :

From : The sender address
Recipient : The receiver address
Data : It's an InputStream type from which we can extract content and relevant information related to the received email like : subject, body, CC, attachments and else.

Let's see how we can extract the content of the email :

Convert to MimeMessage

We can retrieve content from multipart content-typed message using MimeMessage instance.

public MimeMessage convertToMimeMessage(InputStream data) 
throws MessagingException {
        Session session = Session.getDefaultInstance(new Properties());
        try {
            return new MimeMessage(session, data);
        }catch (MessagingException e){
            throw new MessagingException();
        }
    }

Extract email content

To extract the email content, we'll create an ReceivedEmail model to facilitate the processing.

public class ReceivedEmail {

    private String subject;
    private String senderAddress;
    private String senderName;
    private String recipientAddress;
    private String recipientName;
    private String cc;
    private String bcc;
    private String contentType;
    private List<DataSource> attachments = new ArrayList();

    // Getters and setters
    // ...
}

For the sake of simplicity I used String for recipientAddress, CC and BCC but it's can be a list of addresses (example in the code).

We create dedicated service for email content extraction and the extract method could looks like :

public ReceivedEmail extractReceivedEmail(InputStream data) throws Exception {
        ReceivedEmail receivedEmail = new ReceivedEmail();
        MimeMessage message;
        try {
            message = this.convertToMimeMessage(data);
            receivedEmail.setSubject(message.getSubject());
            receivedEmail.setSenderAddress(InternetAddress.toString(message.getFrom()));
            InternetAddress[] recipientAddresses = InternetAddress.parse(InternetAddress.toString(message.getAllRecipients()));
            receivedEmail.setRecipientAddress(InternetAddress.toString(recipientAddresses));
            receivedEmail.setRecipientName(recipientAddresses[0].getPersonal());
            receivedEmail.setContentType(message.getContentType());
            // Use here Apache library for parsing
            MimeMessageParser messageParser = new MimeMessageParser(message);
            messageParser.parse(); // very important to parse before getting data
            receivedEmail.setCc(messageParser.getCc().toString());
            receivedEmail.setBcc(messageParser.getBcc().toString());
            receivedEmail.setAttachments(messageParser.getAttachmentList());
            System.out.println(receivedEmail);
            return receivedEmail;
        } catch (Exception e) {
            throw new Exception();
        }
    }

Now we have a full complete email receiver with minimal lines of code.

Secure SMTP Server

Let's go further step to see how we can secure our mail server.

First thing to do is to indicate that the authentication is required and implement basic auth with username and password.

this.smtpServer = SMTPServer
                .port(25000)
                .simpleMessageListener(marketingMsgListener)
                .requireAuth(true) // auth required
                .authenticationHandlerFactory(easyAuth) // implement type of auth
                .build();

Different implementations of authenticationHandlerFactory can be done, I chose here, again for the sake of simplicity, the EasyAuthenticationHandlerFactory class which needs implementation of the UsernamePasswordValidator interface.

@Configuration
public class SimpleAuthValidatorImpl implements UsernamePasswordValidator {

    private final String CREDENTIALS_LOGIN = "superus3r";
    private final String CREDENTIALS_PASSWORD = "passw0rd";

    @Override
    public void login(String username, String password, MessageContext context) throws LoginFailedException {
        if(CREDENTIALS_LOGIN.equals(username) && CREDENTIALS_PASSWORD.equals(password)){
            System.out.println("Authenticated successfully");
        }else{
            System.err.println("Invalid authentication !");
            throw new LoginFailedException();
        }
    }
}

And this how our SMTPServerConfig looks like :

@Configuration
public class SMTPServerConfig {

    private final SMTPServer smtpServer;
    private final SimpleMessageListener marketingMsgListener;
    private final UsernamePasswordValidator authValidator;
    private final EasyAuthenticationHandlerFactory easyAuth;

    public SMTPServerConfig(SimpleMessageListener marketingMsgListener) {
        authValidator = new SimpleAuthValidatorImpl();
        easyAuth = new EasyAuthenticationHandlerFactory(authValidator);
        this.marketingMsgListener = marketingMsgListener;

        this.smtpServer = SMTPServer
                .port(25000)
                .simpleMessageListener(this.marketingMsgListener)
                .requireAuth(true)
                .authenticationHandlerFactory(easyAuth)
                .build();

        this.smtpServer.start();
    }
}

Go deeper

More parameters can be customised to fit your needs and improve your SubEtha server, I list those below and you can try to explore them to improve your mail receiver implementation :

Max connections and connection timeout
TLS support
Messages size
Shutdown of the SMTP server
Testing

Conclusion

I presented how we can, with small lines of code, write an application that can receive emails, handle those and apply some magic to them with SubEtha SMTP and Spring Boot.

If you have any questions or suggestions, please, leave your comments down below.

Thanks for reading and happy coding.

Resources

Source code : https://github.com/redamessoudi/subethasmtp-springboot.

Header photo by Liam Truong on Unsplash