How to use private Java classes for effective API design

I am writing my first "API jar", which will be an open source library and used by (possibly) other developers I read Joshua block's thesis on effective API design. One of the things he talked about - I never thought of - was his concept of minimizing access and maximizing information hiding Basically, you only want your API developers to access the Java objects they will use, and you don't want your API developers to access any "guts" in your library

In my years as a java developer, I never had to create any classes except public In addition, I have never used nested classes So I'm sitting here wondering how to implement this "information hiding" best practice in my Java API? I think private, possibly nested classes are the answer But where do you start?

>Each Java source files need at least one public class to compile Therefore, for me, private (and non nested) classes, I need to "bundle it with public classes. For me, this makes sense only when public / private classes are closely related. However, if I have a part, my API contains only private classes that are unrelated to any other public analogy (for accessibility minimization purposes) ? > when to nest private classes and when to nest them? Or is it just a matter of preference?

Solution

Personally, I don't believe in private Where feasible, I use protection to allow some of the main benefits of OO design

Basically, the "information hiding" principle is not a guide However, in practice, it should not be blindly followed in all cases For pure principles, as others have suggested, you need to define a set of interfaces as public interfaces and hide all the rest of Lib using packages, private classes, factory methods, etc Given some problems with Java's package – private visibility, in many cases (classes in your lib will want to work across packages –) this is a bit useless, which in turn seems to prevent this approach

In addition, the API always has at least two types of users: basic users, who will use the objects and methods provided by you, and users with complex requirements. They want to modify the behavior of the API through inheritance (at least). Many 'hidden' things will be successfully blocked

Don't be shy about making these things public. These things may be meaningful. Protect those things that don't really need to be made public, and only those private things that may cause harm if they are directly accessed by anything other than directly related code

Another note: the main purpose of the hiding principle is to simplify the use of code by others, and to imply and encourage the correct use of code But remember, documentation is another important means to achieve this goal; In any case, libraries need documents If you have 100 public methods and your document describes that the use case needs 10 such users, your lib user may be as good as him if he can only see those 10