Hiding methods from a public API

[Chris]

We publish a library. Some of the methods in the public classes are
intended for consumption by our customers, but others are just for
internal use. Ok, fine, declare those methods protected.

A difficultly arises when we want to access one of these internal-use
methods from a class in another package. Example:

com.mydomain.foo.MyFoo wants to access a method in
com.mydomain.bar.MyBar

So the method has to be made public, which makes it available to our
customers. Not good.

How do people generally handle this? I've been putting a "Do not use,
for internal use only" in the Javadoc for the method, but that's not ideal.

 

[=?ISO-8859-1?Q?Arne_Vajh=F8j?=]

We publish a library. Some of the methods in the public classes are
intended for consumption by our customers, but others are just for
internal use. Ok, fine, declare those methods protected.

A difficultly arises when we want to access one of these internal-use
methods from a class in another package. Example:

com.mydomain.foo.MyFoo wants to access a method in
com.mydomain.bar.MyBar

So the method has to be made public, which makes it available to our
customers. Not good.

How do people generally handle this? I've been putting a "Do not use,
for internal use only" in the Javadoc for the method, but that's not ideal.

Redesign.

If you have a bar "chunk" that needs to expose some functionality
to the foo "chunk", but you do not want other to use it, then it
indicates a design problem to me.

If you insist on just doing a workaround, then just don't generate
javadocs for that class.

Arne

 

[Stefan Ram]

How do people generally handle this? I've been putting a "Do not use,
for internal use only" in the Javadoc for the method, but that's not ideal.

I have a macro »PRIVATE«. (I am using a preprocessor.)

For the build of the library this is defined as

@de.dclj.ram.meta.description.Private public

Thus, it declares as »public«, but adds an annotation to show
the intend that this is to be considered »private« in regard
to clients of the library.

When I build JavaDocs from the source code,
this macro is being redefined as

private

So, these entries will not show up in the JavaDoc.

I might write a Doclet to implement the same behavior with the
annotation, but the preprocessor approach was easier for the
moment and I can still write the doclet later. (NB: This is a
recent modification and I still have not jet created
documentation since, so it is not tried.)

 

[Thomas Hawtin]

We publish a library. Some of the methods in the public classes are
intended for consumption by our customers, but others are just for
internal use. Ok, fine, declare those methods protected.

I assume you mean default access ("package private"). Can customers not
extend your classes?

A difficultly arises when we want to access one of these internal-use
methods from a class in another package. Example:

If you declare a public interface you expose that, but keep
implementation in a different package for which you do not publish an API.

Inner classes are also useful. Your public class can have an inner class
that uses your unpublished package interface.

Tom Hawtin

 

[Eric Sosman]

Chris wrote On 08/07/07 15:08,:

We publish a library. Some of the methods in the public classes are
intended for consumption by our customers, but others are just for
internal use. Ok, fine, declare those methods protected.

Are you sure you understand what "protected" means?
It means "accessible from all of this package, and also
from any class in any package anywhere at all that just
happens to extend this one, no matter who wrote it."

A difficultly arises when we want to access one of these internal-use
methods from a class in another package. Example:

com.mydomain.foo.MyFoo wants to access a method in
com.mydomain.bar.MyBar

So the method has to be made public, which makes it available to our
customers. Not good.

Sounds like you've painted yourself into a corner.
Or maybe packaged yourself into a corner: Your division
of classes into packages does not reflect the ways those
classes relate to each other (if it did, you wouldn't have
this urge to make cross-package calls to package-private
methods). Arne Vajhøj's advice is good.

How do people generally handle this? I've been putting a "Do not use,
for internal use only" in the Javadoc for the method, but that's not ideal.

There are a couple of ugly hacks you might try, but
they are hacks and they are ugly:

- Deprecate all the "hands-off" methods. This won't
absolutely prevent their use, but may discourage it.

- Give each method an extra "enabler" argument whose
value is a class the customer cannot instantiate.
The way *you* get hold of an instance is to use a
static factory method that checks the identity of
its caller and throws if called from outside your
own suite of packages. (The consensus of another
current thread about this technique is that it is
a Bad Idea.)

 

[Greg R. Broderick]

How do people generally handle this? I've been putting a "Do not use,
for internal use only" in the Javadoc for the method, but that's not ideal.

Publish an interface that doesn't include the methods that you wish to remain
for internal use. Tell your clients to program to the interface instead of
to the concrete class.

Regards

--
---------------------------------------------------------------------
Greg R. Broderick (e-mail address removed)

A. Top posters.
Q. What is the most annoying thing on Usenet?
---------------------------------------------------------------------

 

[Roedy Green]

We publish a library. Some of the methods in the public classes are
intended for consumption by our customers, but others are just for
internal use. Ok, fine, declare those methods protected.

First review http://mindprod.com/jgloss/scope.html
so you are clear on just what the various scope modifiers mean,
particularly protected.

Then consider using a the global rename feature of your favourite IDE
to make the names you don't want others to use ugly, and embarrassing
if caught using them. e.g. prefix them with

"XYZCorp_use_only"
"DO_NOT_USE_"
"May_Disappear_"

 

[Lew]

Publish an interface that doesn't include the methods that you wish to remain
for internal use. Tell your clients to program to the interface instead of
to the concrete class.

In conjunction with that, provide a factory that produces an object of the
interface type, but with the run-time type of your actual proprietary
implementation.