search

google / guava

Google core libraries for Java
Apache License 2.0
50.13k stars 10.88k forks source link

@VisibleForSubpackages annotation #2351

Open gaul opened 8 years ago

gaul commented 8 years ago

Could Guava add a @VisibleForSubpackages annotation? This would be similar to the existing @VisibleForTesting annotation which documents why an interface has more visibility than desired and that external callers should not use it. Specifically I ran into this with Apache jclouds which has a hierarchy of subpackages within a jar, e.g., org.jclouds.s3 and org.jclouds.s3.binders. Classes of the subpackage have public visibility so that the parent package can see them but are unintentionally exported to externally callers. Having @VisibleForSubpackages would warn callers and allow external tools to remove references, e.g., Javadoc, semantic versioning checkers.

If @VisibleForTesting were a more generic term, e.g., @UnfortunatelyVisible, with a user-specified reason, this would address my use case as well as other potential cases. The more generic term also removes confusion between super- and sub-packages in my example. This feature request would also seem to interact with Java 9 module visibility although I do not believe it has a similar source-level annotation.

JanecekPetr commented 8 years ago

Yes, please! Although it it true that most of the time the visibility is for testing, sometimes there are other (sometimes valid) reasons, too, and this might help consolidating the mess around them.

ben-manes commented 8 years ago

Shouldn't Jigsaw modules be the preferred resolution?

kluever commented 8 years ago

@eaftan Have the error prone folks thought about this? (This annotation would be fairly worthless without enforcement...also "subpackages" really aren't a thing in Java...they're just different packages as far as the language is concerned)

eaftan commented 8 years ago

We haven't thought about it; we haven't gotten any requests for it. Any sense of how common this use case is?

Also, I agree with Ben that the long-term solution for this is the module system, but I could understand people not wanting to wait until Java 9 for a solution.

netdpb commented 5 years ago

I'm not sure that "visible for subpackages" is a reasonable thing. In the description of this feature request @gaul wants a type in a subpackage to be visible to its "parent" package.

What exactly is the concept that we're looking to model here? Is it the general concept of "friend" packages? Is that something that can be reasonably enforced by annotations?

Is JPMS in fact the right way to handle this use case?