API: make api not depend on antlr by splitting DetailAST between implementation and interface

[romani]

this issue is for major version bump release.

api should be clean and do not depend on any thirdparty libraries.

antlr dependency was beneficial for quick development , but now it cause a problems during embedding checkstyle in other systems. Antlr classes could conflict with another dependencies of application.
Dependencies to any other third party is also not desirable.

from discussion with eclipse-cs author:
"
Checkstyle itself gains little to nothing from restricting packages. However in OSGI context a bundle (e.g. checkstyle-core) needs declare which of it's packages are visible to extensions.
Today this includes all of Checkstyle's packages and Checkstyle's own dependenceis (antlr, guava, commons-*).

The downside of this in OSGI realm is that those packages are now visible not just to Checkstyle extensions but also do unrelated plugins, which potentially import one of the 3rd-party packages.
This can lead to nasty class version conflicts in unexpected places, e.g. the Checkstyle plugin can potentially break a different plugin.

The main problem is in fact that 3rd-party dependencies today need to be exported in order for (some) checkstyle extensions to work.
"

---

MIGRATION NOTES: all extensions of Checkstyle has to be recompiled with 8.21 version of checkstyle . Example of failure - #3417 (comment)

[rnveach]

@romani I think this can have the checkstyle 8 label.

[rnveach]

@MEZk @romani Right now issue is you don't want to include ANTLR in API packages. DetailAST includes this because of it's class hierarchy and needing some classes for it to function and such.

DetailAST is slightly required for #4419 (comment) and there is talks of breaking apart DetailAST to uniquely identify it without the class, which I don't personally like the looks of.

However, I noticed that this issue doesn't affect DetailNode which also relies on ANTLR. This is because it is a simple interface and includes no references back to ANTLR.
For this issue, should we do the same to DetailAST? Convert it to a simple interface, and move the class' implementation to another location outside of API.

[MEZk]

@rnveach
I like the idea of giving the interface to the API clients instead of the implementations.

[romani]

yes, It is better to use interface, in general I agree, BUT:

• DetailNode was created as internal API for now, and we still did not make a decision to stay with arrays in interface or make it a List (DetailNode[] getChildren(); vs List<DetailNode> getChildren();). Array is old fashioned but strict in size, List is not immutable by type (could be non-modifiable by some implementation, but ....).

• if we make such a revolution in API, I would rather think about it throughly as it will force all Checks to be affected. Alternative is to convert DetailAST to interface and keep all methods so Checks should not be affected if recompiled. In run time old binaries might fail with errors if smth was known as class now become an interface. But this need to be tested.

• I try to avoid one more API that will keep it possible to look at AST as mutable tree.

=================

But probably we could make it into 2 steps: convert to interface and resolve API dependency to ANTRL ; migrate to new AST that is immutable.

[MEZk]

Array is old fashioned but strict in size, List is not immutable by type (could be by some implementation, but ....).

We had the discussion that we could use fully immutable collections. Collections are easier to use, but

• this will lead to addition of a new dependency
• additional memory
• 3rd party lib in API

Thus, I'm for arrays.

I try to avoid one more API that will keep it possible to look at AST as mutable tree.

We can make our inner implementation immutable.

migrate to new AST that is immutable.

Should this AST class be our inner immutable implementation of the DetailAST interface which we will expose to API clients?

[jbduncan]

I don't know if this has been considered already, but AFAICT Checkstyle depends on Guava in some way, so one potential way of achieving List<DetailNode> getChildren(); whilst maintaining runtime immutability would be to return a com.google.common.collect.ImmutableList. Since ImmutableList implements List, this would allow the return type of getChildren(); to be List<DetailNode> whilst disallowing operations like List.set() at runtime, which would otherwise be possible to do on a mutable list or array.

[romani]

whilst maintaining runtime immutability would be to return a com.google.common.collect.ImmutableList

unfortunately dependency to guava is just another pain for applications/plugins that embed checkstyle.
Ones jdk have similar collections, we will drop guava usage completely. Guava is already restricted to minimum in our project. API should not depend on Guava for sure.

[jbduncan]

@romani Okay. IIUC, you think my idea wouldn't work not because you think my idea is to have an API like ImmutableList<DetailAST> getChildren(); (which, to clarify, is not what I had in mind), but because the Checkstyle team is trying to minimise all sorts of dependencies on Guava, including implementation detail dependencies? :)

[romani]

Api signature should not depend on guava, implementation could return runtime-immutable type.
But only and only when implementation of DetailAst is moved out api package.

Right now, DetailAST is implementation in api area . So any update to use guava will result of api dependency to guava that we try to avoid

[romani]

unfortunate fact, just a reminder that API already depends on guava (8 years in play already):

$ grep ".google." src/main/java/com/puppycrawl/tools/checkstyle/api/*
.../api/Configuration.java:import com.google.common.collect.ImmutableMap;
.../api/Context.java:import com.google.common.collect.ImmutableCollection;
.../api/FileContents.java:import com.google.common.collect.ImmutableMap;
.../api/FileText.java:import com.google.common.io.Closeables;

[rnveach]

This issue is blocked by #4609 which is to make an interface for DetailAST.