Add support for databind#5369 (`@JsonFilter` for Collections)

[cowtowncoder]

While FasterXML/jackson-databind#5369 was implemented for Java Collection types (via FasterXML/jackson-databind#5370), Scala module should (eventually) add support through ScalaIteratorSerializer and ScalaIterableSerializer.

[pjfanning]

Scala Collections are separate from Java Collections. jackson-module-scala only has code for Scala Collection support.
I understand that it might be useful to have something similar for Scala Collections but I don't think this is a priority. If we get users requesting it, I might have a look.
I'm not sure how useful is to filter collections when serializing them. If users want this, can't they just filter the collections themselves before serializing?

[cowtowncoder]

Yes, I know Scala collection are distinct technically and need custom handlers. From user perspective they are quite similar, however, hence the issue.

There have been occasional questions, requests suggesting some users would like such filtering.
But it is not one of "most-wanted" features. So I have no issue if priority is left as low; but at least there is some visibility if users bump into discrepancy.

As with most features it has more to do with convenience of getting some behavior than whether something is possible to achieve in general.

[pjfanning]

I added some tests for maps and beans based on jackson-databind tests (added in 2.x/3.x branches today) and they seem ok but #789 demos that changes are needed to address this issue

[pjfanning]

@cowtowncoder @JooHyukKim what if the filter class has an equals method that returns true for many values? The implementation in FasterXML/jackson-databind#5370 passes around a single suppressableValue - I would have thought passing around the filter instance would be a better way to support this - so every collection value can be checked against the filter instance.

[cowtowncoder]

@pjfanning Yes, equals() methods is used in a non-standard way, to support filtering use case, without adding new Filter value type. It's not a design I am particular proud of.
suppressableValue is -- if I remember correctly, that filter object. So not a typical "only filter this value" Object, but something that provides Filter function as equals().

In hindsight, something like java.util.function.Predicate would have been suitable value type to use instead (if JDK 8 was baseline when custom "filter" feature was added).
Anything fancier (passing context to filter, which would be useful for more advanced use cases) would be challenging as annotation types have no access to databind types.

[pjfanning]

Thanks @cowtowncoder - I checked the databind code and I now see how _shouldSerializeElement uses the suppressableValue. I think suppressableValue name is confusing. It sound like it is a value that should be suppressed as opposed to a filter instance. Is there any chance that the new code in 3.x branch could rename this variable (eg filterInstance)? I understand that pre-existing 3.0 code is more difficult to refactor but we could start with the new code that has not been released yet.

[cowtowncoder]

TL;DNR: renaming is a possibility.

@pjfanning We could probably safely change it for Collection/array serializer filtering, but perhaps less likely for POJO or, especially, Map / "Optional" (ReferenceType) filtering.

Although to be completely honest, if we were to do such renaming, 3.1.0 would be the best remaining chance.

Looking at other modules, jackson-datatypes-collections, surprisingly, only refers to _suppressableValue from Guava's GuavaOptionalSerializer.java, but not from anywhere else.

But one point to consider is the replacement name to use: I always got confused about "direction" of filtering (is it "filtering in" -- including match -- or "filtering out" -- excluding match).
So given it is used in:

        if (_suppressableValue != null) {
            if (MARKER_FOR_EMPTY == _suppressableValue) {
                if (ser.isEmpty(ctxt, value)) {
                    return;
                }
            } else if (_suppressableValue.equals(value)) {
                return;
            }
        }

term "suppress" makes some sense to me (if value to serialize "is suppressable", suppress (exclude)).

At any rate, replacement should be named in a way that helps understand logic, or at least not cause more confusion.

Oh... and now I remember reason, I think, for the original naming: it was indeed to simply match a single value.
From BeanPropertyWriter:

    /**
     * Value that is considered default value of the property; used for
     * default-value-suppression if enabled.
     */
    protected final Object _suppressableValue;

which obviously is outdated comment, but explains where the idea came from. And why sort of hack was used for custom filtering -- ability to just piggy-back it.

But I guess I am torn between existing name, "_valueToExclude" or "_filter[Out]Value" or... something else.