Public vs internal APIs

Hi,

I'm looking into implementing java.sql.Struct in the jdbc driver, and
it turns out I do not like PGObject for various reasons.
E.g. it cannot "append itself to a buffer", it ties decoding with
PGObject itself.

I'm going to try another approach, however I would like to avoid
leaking that API to the public API of the driver.

Having said that, I wonder what if we add: @ExperimentalAPI,
@PublicAPI, @InternalAPI kind of annotations, so we can clearly mark
internal classes as, well, internal so our clients would not
accidentally depend on the internal classes?

Java does not yet allow to define "published API" (see [1]), so it
would be nice to mark some APIs as internal.

For instance it makes sense marking the following classes as @InternalAPI:
   org.postgresql.util.LruCache
   org.postgresql.core.Parser
   etc

[1]: http://martinfowler.com/ieeeSoftware/published.pdf

--
Regards,
Vladimir Sitnikov