Deprecate Gson.excluder() exposing internal Excluder class

[Marcono1234]

Resolves #1903

Additionally adds documentation to some Gson methods which did not have documentation yet.

[eamonnmcmanus]

Seems like some people are using this so I'm not sure we can remove it.

[Marcono1234]

Hmm good point. Maybe Gson should then expose (parts of) the Excluder class? It looks like most projects are interested in whether Gson is configured to ignore a certain class (excludeClass) or field (excludeField). Everything else of Excluder can most likely be implemented by the user themselves.
So I think Gson should not directly expose Excluder. These used methods are actually pretty close to the methods of the public ExclusionStrategy interface. The only issue is that it does not differentiate between serialization and deserialization (so Gson would need one serialization and deserialization method which returns an ExclusionStrategy wrapping the underyling Excluder), and that ExclusionStrategy for some reason uses FieldAttributes instead of directly Field. From the Git commit 839b0c2 which added this class it is not entirely clear to my why this was done. Maybe to avoid users messing with the state of the reflection Field object, e.g. whether it is accessible or not.

What do you think? We can also deprecate Gson.excluder() for now, but probably eventually need to do something about this. Or we deprecate it and just wait until people start to complain ...; once they use recent Gson versions with Java module descriptor they will notice that they are using internal classes.

[eamonnmcmanus]

Obviously it was a mistake to add a method to the public API that returns an .internal. type, but I'm not sure we can fix that mistake without making things worse. I think deprecation is probably the way to go, and we probably won't ever remove the method.

[Marcono1234]

Ok, I have repurposed this pull request to only deprecate the excluder() method, saying that it "might be removed in a future version", even if we never remove it.

[eamonnmcmanus]

Thanks!

[kaqqao]

Hi everyone. I'm chiming in as the maintainer of GraphQL SPQR, one of the projects that uses excluder().

It looks like most projects are interested in whether Gson is configured to ignore a certain class (excludeClass) or field (excludeField).

This is exactly our situation. We're generating a GraphQL schema from Java types and, in order to decide what fields to expose, we're effectively interrogating Gson's configuration to make that decision.

Maybe Gson should then expose (parts of) the Excluder class?

For what it's worth, this would suffice and sounds like a very fair approach to me.

[Marcono1234]

@kaqqao, would you mind creating a new feature request issue for this (I don't think one exists yet)? That would probably make it easier to track this request.