Design with Patterns: Elegant Data Mapping

Copyright (c) 2025 Roman Vidayko
www.linkedin.com/in/roman-vidayko

𝗜𝗡𝗧𝗥𝗢

I decided to share my thoughts on how to make a software developer's life simpler and more efficient. It is not my intention to provide all-in-one silver bullets, but rather to offer some mindful ideas with supporting code snippets that provide fundamental understanding.

𝗜𝗡𝗖𝗜𝗧𝗘

Being developing complex software, you've probably encountered the routine of converting a data model from local data types to remote ones and vice versa. Have you ever wondered what ideal data mapping should look like?
Here, I am going to introduce a solution that uses the power of Java and is based on the fundamental principles of Design Patterns. But let's first take a look at how it is usually done to understand the pros and cons.

𝗖𝗢𝗠𝗠𝗢𝗡 𝗣𝗥𝗔𝗖𝗧𝗜𝗖𝗘

Here are a couple of samples sketched out that are present in any project, like the tentacles of the Lernaean Hydra—no matter how many you cut off, new ones will still grow.

𝗢𝗽𝘁𝗶𝗼𝗻 𝟭: 𝗗𝗶𝗿𝗲𝗰𝘁 𝗰𝗼𝗻𝘃𝗲𝗿𝘀𝗶𝗼𝗻

𝚁𝚎𝚖𝚘𝚝𝚎𝚃𝚢𝚙𝚎𝟷 𝚛𝚎𝚖𝚘𝚝𝚎𝚃𝚢𝚙𝚎𝟷 = 𝚗𝚎𝚠 𝚁𝚎𝚖𝚘𝚝𝚎𝚃𝚢𝚙𝚎𝟷(
𝚕𝚘𝚌𝚊𝚕𝚃𝚢𝚙𝚎𝟷.𝚏𝚒𝚎𝚕𝚍𝟷(),
...
𝚕𝚘𝚌𝚊𝚕𝚃𝚢𝚙𝚎𝟷.𝚏𝚒𝚎𝚕𝚍𝙽());

P͟r͟o͟s͟: 𝘐𝘵 𝘪𝘴 𝘴𝘪𝘮𝘱𝘭𝘦, 𝘢𝘯𝘥 𝘺𝘰𝘶 𝘥𝘰𝘯’𝘵 𝘳𝘦𝘢𝘭𝘭𝘺 𝘯𝘦𝘦𝘥 𝘵𝘰 𝘬𝘯𝘰𝘸 𝘑𝘢𝘷𝘢 𝘵𝘰 𝘪𝘮𝘱𝘭𝘦𝘮𝘦𝘯𝘵 𝘵𝘩𝘪𝘴! 🥴
C͟o͟n͟s͟: 𝘛𝘩𝘦 𝘮𝘦𝘵𝘩𝘰𝘥 𝘣𝘰𝘥𝘺 𝘵𝘩𝘢𝘵 𝘤𝘰𝘯𝘵𝘢𝘪𝘯𝘴 𝘪𝘵 𝘪𝘴 𝘴𝘱𝘰𝘪𝘭𝘦𝘥 𝘸𝘪𝘵𝘩 𝘭𝘰𝘨𝘪𝘤 𝘵𝘩𝘢𝘵 𝘪𝘴 𝘰𝘶𝘵 𝘰𝘧 𝘵𝘩𝘦 𝘮𝘦𝘵𝘩𝘰𝘥'𝘴 𝘳𝘦𝘴𝘱𝘰𝘯𝘴𝘪𝘣𝘪𝘭𝘪𝘵𝘺 𝘴𝘤𝘰𝘱𝘦.

𝗢𝗽𝘁𝗶𝗼𝗻 𝟮: 𝗨𝘀𝗮𝗴𝗲 𝗼𝗳 𝗠𝗮𝗽𝗽𝗲𝗿 𝗨𝘁𝗶𝗹𝗶𝘁𝘆 𝗖𝗹𝗮𝘀𝘀

𝚏𝚒𝚗𝚊𝚕 𝚁𝚎𝚖𝚘𝚝𝚎𝚃𝚢𝚙𝚎𝟷 𝚛𝚎𝚖𝚘𝚝𝚎𝚃𝚢𝚙𝚎𝟷 = 𝚂𝚝𝚊𝚝𝚒𝚌𝙼𝚊𝚙𝚙𝚎𝚛.𝚖𝚊𝚙𝚃𝚘𝚁𝚎𝚖𝚘𝚝𝚎𝚃𝚢𝚙𝚎𝟷(𝚕𝚘𝚌𝚊𝚕𝚃𝚢𝚙𝚎𝟷);
...
𝚌𝚕𝚊𝚜𝚜 𝚂𝚝𝚊𝚝𝚒𝚌𝙼𝚊𝚙𝚙𝚎𝚛 {

𝚙𝚞𝚋𝚕𝚒𝚌 𝚜𝚝𝚊𝚝𝚒𝚌 𝚁𝚎𝚖𝚘𝚝𝚎𝚃𝚢𝚙𝚎𝟷 𝚖𝚊𝚙𝚃𝚘𝚁𝚎𝚖𝚘𝚝𝚎𝚃𝚢𝚙𝚎𝟷(𝙻𝚘𝚌𝚊𝚕𝚃𝚢𝚙𝚎𝟷 𝚕𝚘𝚌𝚊𝚕𝚃𝚢𝚙𝚎𝟷){
𝚛𝚎𝚝𝚞𝚛𝚗 𝚗𝚎𝚠 𝚁𝚎𝚖𝚘𝚝𝚎𝚃𝚢𝚙𝚎𝟷(
...,
𝚖𝚊𝚙𝚃𝚘𝚁𝚎𝚖𝚘𝚝𝚎𝚃𝚢𝚙𝚎𝟸(𝚕𝚘𝚌𝚊𝚕𝚃𝚢𝚙𝚎𝟷));
}

𝚙𝚞𝚋𝚕𝚒𝚌 𝚜𝚝𝚊𝚝𝚒𝚌 𝚁𝚎𝚖𝚘𝚝𝚎𝚃𝚢𝚙𝚎𝟸 𝚖𝚊𝚙𝚃𝚘𝚁𝚎𝚖𝚘𝚝𝚎𝚃𝚢𝚙𝚎𝟸(𝙻𝚘𝚌𝚊𝚕𝚃𝚢𝚙𝚎𝟷 𝚕𝚘𝚌𝚊𝚕𝚃𝚢𝚙𝚎𝟷){
𝚛𝚎𝚝𝚞𝚛𝚗 𝚗𝚎𝚠 𝚁𝚎𝚖𝚘𝚝𝚎𝚃𝚢𝚙𝚎𝟸(
...
}
}

P͟r͟o͟s͟: 𝘎𝘰𝘵 𝘳𝘪𝘥 𝘰𝘧 𝘵𝘩𝘦 𝘮𝘢𝘱𝘱𝘪𝘯𝘨 𝘭𝘰𝘨𝘪𝘤 𝘧𝘪𝘹𝘪𝘯𝘨 𝘵𝘩𝘦 𝘮𝘦𝘵𝘩𝘰𝘥'𝘴 𝘴𝘪𝘯𝘨𝘭𝘦 𝘳𝘦𝘴𝘱𝘰𝘯𝘴𝘪𝘣𝘪𝘭𝘪𝘵𝘺.
C͟o͟n͟s͟: 𝘛𝘪𝘨𝘩𝘵 𝘤𝘰𝘶𝘱𝘭𝘪𝘯𝘨 𝘸𝘪𝘵𝘩 𝘤𝘰𝘯𝘴𝘶𝘮𝘦𝘳𝘴, 𝘪𝘯𝘢𝘣𝘪𝘭𝘪𝘵𝘺 𝘵𝘰 𝘤𝘶𝘴𝘵𝘰𝘮𝘪𝘻𝘦 𝘮𝘦𝘵𝘩𝘰𝘥𝘴, 𝘯𝘢𝘮𝘦𝘴𝘱𝘢𝘤𝘦 𝘱𝘰𝘭𝘭𝘶𝘵𝘪𝘰𝘯, 𝘭𝘰𝘸 𝘮𝘢𝘪𝘯𝘵𝘢𝘪𝘯𝘢𝘣𝘪𝘭𝘪𝘵𝘺 𝘰𝘧 𝘶𝘵𝘪𝘭𝘪𝘵𝘺 𝘤𝘭𝘢𝘴𝘴𝘦𝘴, 𝘢𝘯𝘥 𝘱𝘰𝘵𝘦𝘯𝘵𝘪𝘢𝘭 𝘮𝘦𝘮𝘰𝘳𝘺 𝘭𝘦𝘢𝘬𝘴 𝘸𝘩𝘦𝘯 𝘵𝘩𝘦 𝘯𝘶𝘮𝘣𝘦𝘳 𝘰𝘧 𝘴𝘵𝘢𝘵𝘪𝘤 𝘮𝘦𝘵𝘩𝘰𝘥𝘴 𝘨𝘳𝘰𝘸𝘴 𝘶𝘯𝘤𝘰𝘯𝘵𝘳𝘰𝘭𝘭𝘢𝘣𝘭𝘺.

𝗢 𝗕𝗥𝗔𝗩𝗘 𝗡𝗘𝗪 𝗣𝗔𝗜𝗡𝗟𝗘𝗦𝗦 𝗠𝗔𝗣𝗣𝗜𝗡𝗚

Thinking about this, I was looking for a solution that has a strong, clear pattern with a minimal number of checkpoints, something simple to understand and implement. It should be so clear and simple that my peers will be inclined to follow it, rather than improvising with rudimentary hacks.
The basis of this solution involves two design patterns: 𝘚𝘵𝘳𝘢𝘵𝘦𝘨𝘺 and 𝘚𝘦𝘳𝘷𝘪𝘤𝘦 𝘓𝘰𝘤𝘢𝘵𝘰𝘳. The 𝘚𝘵𝘳𝘢𝘵𝘦𝘨𝘪𝘦𝘴 will perform the mapping, and the 𝘚𝘦𝘳𝘷𝘪𝘤𝘦 𝘓𝘰𝘤𝘢𝘵𝘰𝘳 will be responsible for selecting the right mappers. Additionally, the 𝘊𝘰𝘯𝘵𝘦𝘹𝘵 𝘖𝘣𝘫𝘦𝘤𝘵 pattern is involved. This is because local and remote data sometimes only partially overlap, and the 𝘊𝘰𝘯𝘵𝘦𝘹𝘵 𝘖𝘣𝘫𝘦𝘤𝘵 is designed to bring together all the data that needs to be contained by a target data type.
That’s a lot of words, let’s jump into f̶i̶g̶h̶t̶ coding!

𝗛𝗢𝗪 𝗧𝗢 𝗨𝗦𝗘

// 𝙼𝚊𝚙𝚙𝚒𝚗𝚐 𝚝𝚘 𝚛𝚎𝚖𝚘𝚝𝚎 𝙰𝙿𝙸 𝚍𝚊𝚝𝚊𝚝𝚢𝚙𝚎
𝚏𝚒𝚗𝚊𝚕 𝚃𝚢𝚙𝚎𝟷 𝚝𝚢𝚙𝚎𝟷 = 𝚖𝚊𝚙𝚙𝚎𝚛𝙻𝚘𝚌𝚊𝚝𝚘𝚛.𝚖𝚊𝚙(𝚗𝚎𝚠 𝚃𝚢𝚙𝚎𝟷𝙲𝚘𝚗𝚝𝚎𝚡𝚝(𝚝𝚢𝚙𝚎𝟷𝙲𝚘𝚗𝚝𝚎𝚡𝚝𝙳𝚊𝚝𝚊));

// 𝙲𝚊𝚕𝚕𝚒𝚗𝚐 𝚛𝚎𝚖𝚘𝚝𝚎 𝙰𝙿𝙸
𝚏𝚒𝚗𝚊𝚕 𝚃𝚢𝚙𝚎𝟸 𝚝𝚢𝚙𝚎𝟸 = 𝚛𝚎𝚖𝚘𝚝𝚎𝙰𝚙𝚒𝙰𝚍𝚊𝚙𝚝𝚎𝚛.𝚐𝚎𝚝𝚁𝚎𝚖𝚘𝚝𝚎𝙳𝚊𝚝𝚊(𝚝𝚢𝚙𝚎𝟷);

// 𝙼𝚊𝚙𝚙𝚒𝚗𝚐 𝚝𝚘 𝚕𝚘𝚌𝚊𝚕 𝚍𝚊𝚝𝚊𝚝𝚢𝚙𝚎 𝚏𝚛𝚘𝚖 𝚛𝚎𝚖𝚘𝚝𝚎 𝙰𝙿𝙸 𝚍𝚊𝚝𝚊𝚝𝚢𝚙𝚎
𝚃𝚢𝚙𝚎𝟹 𝚝𝚢𝚙𝚎𝟹 = 𝚖𝚊𝚙𝚙𝚎𝚛𝙻𝚘𝚌𝚊𝚝𝚘𝚛.𝚖𝚊𝚙(𝚗𝚎𝚠 𝚃𝚢𝚙𝚎𝟹𝙲𝚘𝚗𝚝𝚎𝚡𝚝(𝚝𝚢𝚙𝚎𝟸));

How do you like the way the new mapping looks? Easy-peasy? Just calling the mapperLocator's single method, and that's it!
Let’s go under the hood and see if the technical side of the solution is just as wonderful?

𝗦𝗜𝗥 𝗠𝗔𝗣𝗣𝗘𝗥-𝗟𝗢𝗖𝗔𝗧𝗢𝗥

𝚙𝚞𝚋𝚕𝚒𝚌 𝚌𝚕𝚊𝚜𝚜 𝙼𝚊𝚙𝚙𝚎𝚛𝙻𝚘𝚌𝚊𝚝𝚘𝚛 {
𝚙𝚛𝚒𝚟𝚊𝚝𝚎 𝚏𝚒𝚗𝚊𝚕 𝙼𝚊𝚙<𝙲𝚕𝚊𝚜𝚜<𝚂𝚘𝚞𝚛𝚌𝚎>, 𝙼𝚊𝚙𝚙𝚎𝚛<? 𝚎𝚡𝚝𝚎𝚗𝚍𝚜 𝚂𝚘𝚞𝚛𝚌𝚎, ?>> 𝚖𝚊𝚙𝚙𝚎𝚛𝚜 = 𝚗𝚎𝚠 𝙷𝚊𝚜𝚑𝙼𝚊𝚙<>();

𝚙𝚞𝚋𝚕𝚒𝚌 𝙼𝚊𝚙𝚙𝚎𝚛𝙻𝚘𝚌𝚊𝚝𝚘𝚛(𝙻𝚒𝚜𝚝<𝙼𝚊𝚙𝚙𝚎𝚛<? 𝚎𝚡𝚝𝚎𝚗𝚍𝚜 𝚂𝚘𝚞𝚛𝚌𝚎, ?>> 𝚖𝚊𝚙𝚙𝚎𝚛𝚜) {
𝚖𝚊𝚙𝚙𝚎𝚛𝚜.𝚜𝚝𝚛𝚎𝚊𝚖().𝚏𝚘𝚛𝙴𝚊𝚌𝚑(𝚝𝚑𝚒𝚜::𝚛𝚎𝚐𝚒𝚜𝚝𝚎𝚛);
}

𝚙𝚛𝚒𝚟𝚊𝚝𝚎 𝚟𝚘𝚒𝚍 𝚛𝚎𝚐𝚒𝚜𝚝𝚎𝚛(𝙼𝚊𝚙𝚙𝚎𝚛<? 𝚎𝚡𝚝𝚎𝚗𝚍𝚜 𝚂𝚘𝚞𝚛𝚌𝚎, ?> 𝚖𝚊𝚙𝚙𝚎𝚛){
𝚖𝚊𝚙𝚙𝚎𝚛𝚜.𝚙𝚞𝚝(𝚐𝚎𝚝𝚂𝚘𝚞𝚛𝚌𝚎𝚃𝚢𝚙𝚎(𝚖𝚊𝚙𝚙𝚎𝚛), 𝚖𝚊𝚙𝚙𝚎𝚛);
}

𝚙𝚞𝚋𝚕𝚒𝚌 <𝚃> 𝚃 𝚖𝚊𝚙(𝚂𝚘𝚞𝚛𝚌𝚎 𝚜𝚘𝚞𝚛𝚌𝚎) {
𝚛𝚎𝚝𝚞𝚛𝚗 ((𝙼𝚊𝚙𝚙𝚎𝚛<𝚂𝚘𝚞𝚛𝚌𝚎, 𝚃>) 𝚖𝚊𝚙𝚙𝚎𝚛𝚜.𝚐𝚎𝚝(𝚜𝚘𝚞𝚛𝚌𝚎.𝚐𝚎𝚝𝙲𝚕𝚊𝚜𝚜())).𝚖𝚊𝚙(𝚜𝚘𝚞𝚛𝚌𝚎);
}

𝚙𝚛𝚒𝚟𝚊𝚝𝚎 𝙲𝚕𝚊𝚜𝚜<𝚂𝚘𝚞𝚛𝚌𝚎> 𝚐𝚎𝚝𝚂𝚘𝚞𝚛𝚌𝚎𝚃𝚢𝚙𝚎(𝙼𝚊𝚙𝚙𝚎𝚛<? 𝚎𝚡𝚝𝚎𝚗𝚍𝚜 𝚂𝚘𝚞𝚛𝚌𝚎, ?> 𝚖𝚊𝚙𝚙𝚎𝚛) {
// 𝚂𝚘𝚖𝚎 𝙹𝚊𝚟𝚊 𝚁𝚎𝚏𝚕𝚎𝚌𝚝𝚒𝚘𝚗 𝚌𝚘𝚍𝚎 𝚠𝚑𝚊𝚝 𝚒𝚍𝚎𝚗𝚝𝚒𝚏𝚒𝚎𝚜 𝚝𝚑𝚎 𝚜𝚘𝚞𝚛𝚌𝚎 𝚍𝚊𝚝𝚊-𝚝𝚢𝚙𝚎 𝚏𝚘𝚛 𝚊 𝚖𝚊𝚙𝚙𝚎𝚛
}
}

No magic, just an ordinary job. The source types are keys to identify the right mapper. Source is just a marker interface. Simply supply the mapper instances to the constructor, or declare them as beans if it's a Spring application.

𝗧𝗛𝗘 𝗠𝗜𝗡𝗜𝗢𝗡𝗦

𝚙𝚞𝚋𝚕𝚒𝚌 𝚒𝚗𝚝𝚎𝚛𝚏𝚊𝚌𝚎 𝙼𝚊𝚙𝚙𝚎𝚛<𝚂𝚘𝚞𝚛𝚌𝚎, 𝚃> {
𝚃 𝚖𝚊𝚙(𝚂𝚘𝚞𝚛𝚌𝚎 𝚜𝚘𝚞𝚛𝚌𝚎);
}

𝚙𝚞𝚋𝚕𝚒𝚌 𝚌𝚕𝚊𝚜𝚜 𝚃𝚢𝚙𝚎𝟸𝙼𝚊𝚙𝚙𝚎𝚛 𝚒𝚖𝚙𝚕𝚎𝚖𝚎𝚗𝚝𝚜 𝙼𝚊𝚙𝚙𝚎𝚛<𝚃𝚢𝚙𝚎𝟸𝙲𝚘𝚗𝚝𝚎𝚡𝚝, 𝚃𝚢𝚙𝚎𝟸> {
@𝙾𝚟𝚎𝚛𝚛𝚒𝚍𝚎
𝚙𝚞𝚋𝚕𝚒𝚌 𝚃𝚢𝚙𝚎𝟸 𝚖𝚊𝚙(𝚃𝚢𝚙𝚎𝟸𝙲𝚘𝚗𝚝𝚎𝚡𝚝 𝚜𝚘𝚞𝚛𝚌𝚎) {
𝚛𝚎𝚝𝚞𝚛𝚗 𝚗𝚎𝚠 𝚃𝚢𝚙𝚎𝟸(𝚜𝚘𝚞𝚛𝚌𝚎.𝚏𝚒𝚎𝚕𝚍𝟷, ... , 𝚜𝚘𝚞𝚛𝚌𝚎.𝚏𝚒𝚎𝚕𝚍𝙽);
}
}

𝚙𝚞𝚋𝚕𝚒𝚌 𝚌𝚕𝚊𝚜𝚜 𝚃𝚢𝚙𝚎𝟷𝙼𝚊𝚙𝚙𝚎𝚛 𝚒𝚖𝚙𝚕𝚎𝚖𝚎𝚗𝚝𝚜 𝙼𝚊𝚙𝚙𝚎𝚛<𝚃𝚢𝚙𝚎𝟷𝙲𝚘𝚗𝚝𝚎𝚡𝚝, 𝚃𝚢𝚙𝚎𝟷> {
@𝙰𝚞𝚝𝚘𝚠𝚒𝚛𝚎𝚍 @𝙻𝚊𝚣𝚢
𝚙𝚛𝚒𝚟𝚊𝚝𝚎 𝙼𝚊𝚙𝚙𝚎𝚛𝙻𝚘𝚌𝚊𝚝𝚘𝚛 𝚖𝚊𝚙𝚙𝚎𝚛𝙻𝚘𝚌𝚊𝚝𝚘𝚛;

@𝙾𝚟𝚎𝚛𝚛𝚒𝚍𝚎
𝚙𝚞𝚋𝚕𝚒𝚌 𝚃𝚢𝚙𝚎𝟷 𝚖𝚊𝚙(𝚃𝚢𝚙𝚎𝟷𝙲𝚘𝚗𝚝𝚎𝚡𝚝 𝚜𝚘𝚞𝚛𝚌𝚎) {
𝚏𝚒𝚗𝚊𝚕 𝚃𝚢𝚙𝚎𝟸 𝚝𝚢𝚙𝚎𝟸 = 𝚖𝚊𝚙𝚙𝚎𝚛𝙻𝚘𝚌𝚊𝚝𝚘𝚛.𝚖𝚊𝚙(𝚗𝚎𝚠 𝚃𝚢𝚙𝚎𝟸𝙲𝚘𝚗𝚝𝚎𝚡𝚝(𝚜𝚘𝚞𝚛𝚌𝚎.𝚏𝚒𝚎𝚕𝚍𝚇, 𝚏𝚒𝚎𝚕𝚍𝚈));
𝚛𝚎𝚝𝚞𝚛𝚗 𝚗𝚎𝚠 𝚃𝚢𝚙𝚎𝟷(𝚜𝚘𝚞𝚛𝚌𝚎.𝚏𝚒𝚎𝚕𝚍𝟷, ... , 𝚜𝚘𝚞𝚛𝚌𝚎.𝚏𝚒𝚎𝚕𝚍𝙽, 𝚝𝚢𝚙𝚎𝟸);
}
}

This is the last thing needed to implement. Mappers are just mappers, well distinguished by the MapperLocator. By the way, they allow you to call the MapperLocator from inside for doing nested mapping.

𝗣𝗥𝗢𝗦

Simple to use, easy to increase mapping coverage, loose coupling, atomicity of mappers, easy testing and maintenance, and regular JVM garbage collection is efficient.

𝗖𝗢𝗡𝗦

The entry-level requirements for developers are higher, requiring code reviews and proper test coverage.

𝗦𝗨𝗠𝗠𝗔𝗥𝗬

What is the way to use this solution once it’s introduced? Simply add a 𝘕𝘦𝘸𝘛𝘺𝘱𝘦𝘔𝘢𝘱𝘱𝘦𝘳, a 𝘕𝘦𝘸𝘛𝘺𝘱𝘦𝘊𝘰𝘯𝘵𝘦𝘹𝘵, and supply the new mapper to the 𝘔𝘢𝘱𝘱𝘦𝘳𝘓𝘰𝘤𝘢𝘵𝘰𝘳. Then call the new mapper via the mapperLocator's 𝘮𝘢𝘱() method.

𝘖𝘳𝘪𝘨𝘪𝘯𝘢𝘭 𝘢𝘳𝘵𝘪𝘤𝘭𝘦: https://github.com/roman-vidayko/articles/blob/main/a001/src/content/article_data_mapping.txt

𝘚𝘵𝘢𝘳𝘵𝘪𝘯𝘨 𝘱𝘰𝘪𝘯𝘵 𝘵𝘰 𝘭𝘦𝘢𝘳𝘯 𝘵𝘩𝘦 𝘤𝘰𝘥𝘦: https://github.com/roman-vidayko/articles/blob/main/a001/src/main/java/com/vidayko/service/CustomerApiService.java#L38-L53