The public
modifier in Java allows types, methods, constructors, and fields to be accessed from any other class in the system capable of linking against the defining type.
Thus it forms part of the API, as do protected
members.
However in some cases use of these access modifiers are forced for technical reasons rather than out of an intent to define an API:
a method might need to be accessed from a class in another package in the same plugin, preventing use of default package access;
an @Extension
needs to be public
to allow the Jenkins service loader to instantiate it;
a FormValidation doCheckName(@QueryParameter String value)
method must be public
to expose it as a Stapler web method and thus to JavaScript on a form.
In such cases you should block the member from being used by outside code:
nonessential API additions are at risk of being used in unintended ways
and forcing your plugin to maintain the member more or less forever lest backward compatibility be broken.
This can be accomplished by use of a special annotation available in Jenkins code:
@Restricted(NoExternalUse.class)
@Extension
public class MyListener extends ItemListener {/* … */}
Other plugins attempting to refer to MyListener
will receive a build-time error.
Therefore you are free to rename, move, delete, or otherwise modify MyListener
at any time.
Several kinds of restriction are available; consult Javadoc for details.
This system has no effect on accesses using java.lang.reflect
.