task: better document property mapping #40873
Draft
+27
−2
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
closes: keycloak#40872 Signed-off-by: Steve Hawkins <shawkins@redhat.com>
mabartos
reviewed
Jul 3, 2025
Comment on lines
+102
to
+118
| /** | ||
| * This is the heart of the property mapping logic. In preference order we are looking for: | ||
| * <ul> | ||
| * <li>the "from" value (the property is directly specified) | ||
| * <li>the mapFrom (the property is inferred from another value) | ||
| * <li>the default | ||
| * </ul> | ||
| * | ||
| * <p> | ||
| * If we did not find a value, we simply move on in the interceptor chain. | ||
| * <p> | ||
| * If we found a value, it needs to be transformed via {@link #transformValue(String, ConfigValue, ConfigSourceInterceptorContext, boolean)}. If the mapFrom value is being used or the name matches "to", the | ||
| * either the parentMapper (from {@link PropertyMapper.Builder} mapFrom methods), or the mapper (from {@link PropertyMapper.Builder} transformer methods) is applied. | ||
| * <p> | ||
| * Finally the returned {@link ConfigValue} is made to match what was requested - with the name, value, rawValue, and ordinal set appropriately. | ||
| * <p> | ||
| */ |
There was a problem hiding this comment.
@shawkins Thanks for creating this PR!
Suggested change
| /** | |
| * This is the heart of the property mapping logic. In preference order we are looking for: | |
| * <ul> | |
| * <li>the "from" value (the property is directly specified) | |
| * <li>the mapFrom (the property is inferred from another value) | |
| * <li>the default | |
| * </ul> | |
| * | |
| * <p> | |
| * If we did not find a value, we simply move on in the interceptor chain. | |
| * <p> | |
| * If we found a value, it needs to be transformed via {@link #transformValue(String, ConfigValue, ConfigSourceInterceptorContext, boolean)}. If the mapFrom value is being used or the name matches "to", the | |
| * either the parentMapper (from {@link PropertyMapper.Builder} mapFrom methods), or the mapper (from {@link PropertyMapper.Builder} transformer methods) is applied. | |
| * <p> | |
| * Finally the returned {@link ConfigValue} is made to match what was requested - with the name, value, rawValue, and ordinal set appropriately. | |
| * <p> | |
| */ | |
| /** | |
| * This is the heart of the property mapping logic. In the first step, we need to find the value of the property and then transform it into a form of our needs. | |
| * <p> | |
| * | |
| * <b>1. Find value</b> | |
| * <p> | |
| * In preference order we are looking for: | |
| * <pre> | |
| * [ {@link #from} ] ---> [ {@link #mapFrom} ] ---> [ default ] ---> [try other external] | |
| * (explicit) (derived) (fallback) | |
| * </pre> | |
| * <ul> | |
| * <li>the {@link #from} value (the property is directly specified) | |
| * <li>the {@link #mapFrom} value (the property is inferred from another value) | |
| * <li>the default | |
| * <li>If we did not find a value, we simply move on in the interceptor chain. | |
| * </ul> | |
| * <p> | |
| * | |
| * <b>2. Transform found value</b> | |
| * <p> | |
| * If we found a value for the attribute name, it needs to be transformed via {@link #transformValue} method. How to transform it? | |
| * <pre> | |
| * [ name = {@link #from} ? ] ---> [ name = {@link #to} ? ] ---> [ value from parent ? ] | |
| * | y | y | y | |
| * | | | | |
| * value transform(value) parent.transform(value) | |
| * </pre> | |
| * <ul> | |
| * <li>If the name matches {@link #to}, we use the {@link #mapper} from the {@link PropertyMapper.Builder#transformer} method. | |
| * <li>If we found the value on the parent side ({@link #mapFrom}), we use the {@link #parentMapper} specified either via {@link PropertyMapper.Builder#mapFrom(Option, ValueMapper)} method or parent's {@link PropertyMapper.Builder#transformer} method. | |
| * </ul> | |
| * <p> | |
| * Finally the returned {@link ConfigValue} is made to match what was requested - with the name, value, rawValue, and ordinal set appropriately. | |
| */ |
I took it a little bit further to provide at least some illustration of the process to make it more understandable.
Here how it looks like in my IDE with all these formatting:
@shawkins WDYT? And please check if the info is valid.
There was a problem hiding this comment.
Looks good, but I'd say that the transformValue logic would be better described as:
if name == from || value from parent then apply applicable mapper
Alternatively it might be better to just refer to that method here and add some docs there.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
closes: #40872
@mabartos this isn't quite a diagram, but it might be helpful. Additionally, more javadocs could be added to the builder methods.