Update package-info.java files to include the @PublicAPI annotation to indicate
whether any or all of the classes in that package are intended to be part of
the public API.  Further, mark all classes that we intend to be part of the
public API with the @PublicAPI annotation to indicate the ways in which they
may be used.  Note that the use of these annotations and the ultimate
determination as to what is in our public API and the ways in which those
elements may be used still needs to be carefully reviewed before the 1.0
release.

Also, perform minor cleanup in various places througout the code.  This
includes:

- Eliminate the use of protected fields in classes that are in the
org.opends.server.api package (and the classes that extend them).  The use of
protected fields can be troublesome, and there are generally better ways to
accomplish the same thing.

- Eliminate the use of the {@inheritDoc} Javadoc tag in classes that are
intended to be part of the public API.  Some IDEs don't resolve {@inheritDoc}
to show the actual documentation.  Further, there were problems in the way
that some instances of {@inheritDoc} were used, namely having a method sourced
from multiple parents, and in some cases {@inheritDoc} was used to refer to
code defined outside of the OpenDS codebase, which will not be properly handled
by the javadoc utility.

- Update a number of public API classes to mark them as final if we do not
intend for them to be overridden.  Further, for some classes that cannot be
marked final, mark some methods final if we do not intend for those methods to
be overridden.