ReadOnlyObjects.java

package org.kohsuke.github.example.dataobject;

import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.annotation.JsonSetter;
import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;

import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.Objects;

import javax.annotation.Nonnull;

/**
 * {@link org.kohsuke.github.GHMeta} wraps the list of GitHub's IP addresses.
 * <p>
 * This class is used to show examples of different ways to create simple read-only data objects. For data objects that
 * can be modified, perform actions, or get other objects we'll need other examples.
 * <p>
 * IMPORTANT: There is no one right way to do this, but there are better and worse.
 * <ul>
 * <li>Better: {@link GHMetaGettersUnmodifiable} is a good balance of clarity and brevity</li>
 * <li>Worse: {@link GHMetaPublic} exposes setters that are not needed, making it unclear that fields are actually
 * read-only</li>
 * </ul>
 *
 * @author Liam Newman
 * @see org.kohsuke.github.GHMeta
 * @see <a href="https://developer.github.com/v3/meta/#meta">Get Meta</a>
 */
public final class ReadOnlyObjects {

    /**
     * All GHMeta data objects should expose these values.
     *
     * @author Liam Newman
     */
    public interface GHMetaExample {
        /**
         * Gets api.
         *
         * @return the api
         */
        List<String> getApi();

        /**
         * Gets git.
         *
         * @return the git
         */
        List<String> getGit();

        /**
         * Gets hooks.
         *
         * @return the hooks
         */
        List<String> getHooks();

        /**
         * Gets importer.
         *
         * @return the importer
         */
        List<String> getImporter();

        /**
         * Gets pages.
         *
         * @return the pages
         */
        List<String> getPages();

        /**
         * Gets web.
         *
         * @return the web
         */
        List<String> getWeb();

        /**
         * Is verifiable password authentication boolean.
         *
         * @return the boolean
         */
        boolean isVerifiablePasswordAuthentication();
    }

    /**
     * This version uses only public getters and returns unmodifiable lists and has final fields
     * <p>
     * Pro:
     * <ul>
     * <li>Moderate amount of code</li>
     * <li>More annotations</li>
     * <li>Fields final and lists unmodifiable</li>
     * </ul>
     * Con:
     * <ul>
     * <li>Extra allocations - default array lists will be replaced by Jackson (yes, even though they are final)</li>
     * <li>Added constructor is annoying</li>
     * <li>If this object could be refreshed or populated, then the final is misleading (and possibly buggy)</li>
     * </ul>
     *
     * @author Liam Newman
     * @see org.kohsuke.github.GHMeta
     */
    public static class GHMetaGettersFinal implements GHMetaExample {

        private final List<String> api = new ArrayList<>();
        private final List<String> git = new ArrayList<>();
        private final List<String> hooks = new ArrayList<>();
        private final List<String> importer = new ArrayList<>();
        private final List<String> pages = new ArrayList<>();
        private final boolean verifiablePasswordAuthentication;
        private final List<String> web = new ArrayList<>();

        @JsonCreator
        private GHMetaGettersFinal(
                @JsonProperty("verifiable_password_authentication") boolean verifiablePasswordAuthentication) {
            // boolean fields when final seem to be really final, so we have to switch to constructor
            this.verifiablePasswordAuthentication = verifiablePasswordAuthentication;
        }

        public List<String> getApi() {
            return Collections.unmodifiableList(api);
        }

        public List<String> getGit() {
            return Collections.unmodifiableList(git);
        }

        public List<String> getHooks() {
            return Collections.unmodifiableList(hooks);
        }

        public List<String> getImporter() {
            return Collections.unmodifiableList(importer);
        }

        public List<String> getPages() {
            return Collections.unmodifiableList(pages);
        }

        public List<String> getWeb() {
            return Collections.unmodifiableList(web);
        }

        public boolean isVerifiablePasswordAuthentication() {
            return verifiablePasswordAuthentication;
        }
    }

    /**
     * This version uses only public getters and returns unmodifiable lists
     * <p>
     * Pro:
     * <ul>
     * <li>Fields final and lists unmodifiable</li>
     * <li>Construction behavior can be controlled - if values depended on each other or needed to be set in a specific
     * order, this could do that.</li>
     * <li>JsonProrperty "required" works on JsonCreator constructors - lets annotation define required values</li>
     * </ul>
     * Con:
     * <ul>
     * <li>There is no way you'd know about this without some research</li>
     * <li>Specific annotations needed</li>
     * <li>Nonnull annotations are misleading - null value is not checked even for "required" constructor
     * parameters</li>
     * <li>Brittle and verbose - not friendly to large number of fields</li>
     * </ul>
     *
     * @author Liam Newman
     * @see org.kohsuke.github.GHMeta
     */
    public static class GHMetaGettersFinalCreator implements GHMetaExample {

        private final List<String> api;
        private final List<String> git;
        private final List<String> hooks;
        private final List<String> importer;
        private final List<String> pages;
        private final boolean verifiablePasswordAuthentication;
        private final List<String> web;

        /**
         *
         * @param hooks
         *            the hooks - required property works, but only on creator json properties like this, ignores
         *            Nonnull, checked manually
         * @param git
         *            the git list - required property works, but only on creator json properties like this, misleading
         *            Nonnull annotation
         * @param web
         *            the web list - misleading Nonnull annotation
         * @param api
         *            the api list - misleading Nonnull annotation
         * @param pages
         *            the pages list - misleading Nonnull annotation
         * @param importer
         *            the importer list - misleading Nonnull annotation
         * @param verifiablePasswordAuthentication
         *            true or false
         */
        @JsonCreator
        private GHMetaGettersFinalCreator(@Nonnull @JsonProperty(value = "hooks", required = true) List<String> hooks,
                @Nonnull @JsonProperty(value = "git", required = true) List<String> git,
                @Nonnull @JsonProperty("web") List<String> web,
                @Nonnull @JsonProperty("api") List<String> api,
                @Nonnull @JsonProperty("pages") List<String> pages,
                @Nonnull @JsonProperty("importer") List<String> importer,
                @JsonProperty("verifiable_password_authentication") boolean verifiablePasswordAuthentication) {

            // to ensure a value is actually not null we still have to do a null check
            Objects.requireNonNull(hooks);

            this.verifiablePasswordAuthentication = verifiablePasswordAuthentication;
            this.hooks = Collections.unmodifiableList(hooks);
            this.git = Collections.unmodifiableList(git);
            this.web = Collections.unmodifiableList(web);
            this.api = Collections.unmodifiableList(api);
            this.pages = Collections.unmodifiableList(pages);
            this.importer = Collections.unmodifiableList(importer);
        }

        @SuppressFBWarnings(value = { "EI_EXPOSE_REP" }, justification = "Unmodifiable but spotbugs doesn't detect")
        public List<String> getApi() {
            return api;
        }

        @SuppressFBWarnings(value = { "EI_EXPOSE_REP" }, justification = "Unmodifiable but spotbugs doesn't detect")
        public List<String> getGit() {
            return git;
        }

        @SuppressFBWarnings(value = { "EI_EXPOSE_REP" }, justification = "Unmodifiable but spotbugs doesn't detect")
        public List<String> getHooks() {
            return hooks;
        }

        @SuppressFBWarnings(value = { "EI_EXPOSE_REP" }, justification = "Unmodifiable but spotbugs doesn't detect")
        public List<String> getImporter() {
            return importer;
        }

        @SuppressFBWarnings(value = { "EI_EXPOSE_REP" }, justification = "Unmodifiable but spotbugs doesn't detect")
        public List<String> getPages() {
            return pages;
        }

        @SuppressFBWarnings(value = { "EI_EXPOSE_REP" }, justification = "Unmodifiable but spotbugs doesn't detect")
        public List<String> getWeb() {
            return web;
        }

        public boolean isVerifiablePasswordAuthentication() {
            return verifiablePasswordAuthentication;
        }
    }

    /**
     * This version uses only public getters and returns unmodifiable lists.
     *
     *
     * <p>
     * Pro:
     * <ul>
     * <li>Very Easy to create</li>
     * <li>Minimal code</li>
     * <li>Minimal annotations</li>
     * <li>Fields effectively final and lists unmodifiable</li>
     * </ul>
     * Con:
     * <ul>
     * <li>Effectively final is not quite really final</li>
     * <li>If one of the lists were missing (an option member, for example), it will throw NPE but we could mitigate by
     * checking for null or assigning a default.</li>
     * </ul>
     *
     * @author Liam Newman
     * @see org.kohsuke.github.GHMeta
     */
    public static class GHMetaGettersUnmodifiable implements GHMetaExample {

        private List<String> api;

        private List<String> git;
        private List<String> hooks;
        /**
         * If this were an optional member, we could fill it with an empty list by default.
         */
        private List<String> importer = new ArrayList<>();
        private List<String> pages;
        @JsonProperty("verifiable_password_authentication")
        private boolean verifiablePasswordAuthentication;
        private List<String> web;
        /**
         * Create default GHMetaGettersUnmodifiable instance
         */
        public GHMetaGettersUnmodifiable() {
        }

        public List<String> getApi() {
            return Collections.unmodifiableList(api);
        }

        public List<String> getGit() {
            return Collections.unmodifiableList(git);
        }

        public List<String> getHooks() {
            return Collections.unmodifiableList(hooks);
        }

        public List<String> getImporter() {
            return Collections.unmodifiableList(importer);
        }

        public List<String> getPages() {
            return Collections.unmodifiableList(pages);
        }

        public List<String> getWeb() {
            return Collections.unmodifiableList(web);
        }

        public boolean isVerifiablePasswordAuthentication() {
            return verifiablePasswordAuthentication;
        }
    }

    /**
     * This version uses public getters and shows that package or private setters both can be used by jackson. You can
     * check this by running in debug and setting break points in the setters.
     *
     * <p>
     * Pro:
     * <ul>
     * <li>Easy to create</li>
     * <li>Not much code</li>
     * <li>Some annotations</li>
     * </ul>
     * Con:
     * <ul>
     * <li>Exposes some package setters for fields that should not be changed, better than public</li>
     * <li>Lists modifiable when they should not be changed</li>
     * </ul>
     *
     * @author Liam Newman
     * @see org.kohsuke.github.GHMeta
     */
    public static class GHMetaPackage implements GHMetaExample {

        private List<String> api;

        private List<String> git;
        private List<String> hooks;
        /**
         * Missing {@link JsonProperty} or having it on the field will cause Jackson to ignore getters and setters.
         */
        @JsonProperty
        private List<String> importer;
        private List<String> pages;
        private boolean verifiablePasswordAuthentication;
        private List<String> web;

        /**
         * Create default GHMetaPackage instance
         */
        public GHMetaPackage() {
        }

        @JsonProperty
        @SuppressFBWarnings(value = { "EI_EXPOSE_REP" }, justification = "Noted above")
        public List<String> getApi() {
            return api;
        }

        @SuppressFBWarnings(value = { "EI_EXPOSE_REP" }, justification = "Noted above")
        public List<String> getGit() {
            return git;
        }

        @JsonProperty
        @SuppressFBWarnings(value = { "EI_EXPOSE_REP" }, justification = "Noted above")
        public List<String> getHooks() {
            return hooks;
        }

        /**
         * Missing {@link JsonProperty} or having it on the field will cause Jackson to ignore getters and setters.
         *
         * @return list of importer addresses
         */
        @SuppressFBWarnings(value = { "EI_EXPOSE_REP" }, justification = "Noted above")
        public List<String> getImporter() {
            return importer;
        }

        @JsonProperty
        @SuppressFBWarnings(value = { "EI_EXPOSE_REP" }, justification = "Noted above")
        public List<String> getPages() {
            return pages;
        }

        @SuppressFBWarnings(value = { "EI_EXPOSE_REP" }, justification = "Noted above")
        public List<String> getWeb() {
            return web;
        }

        @JsonProperty("verifiable_password_authentication")
        public boolean isVerifiablePasswordAuthentication() {
            return verifiablePasswordAuthentication;
        }

        /**
         * Setters can be private (or package local) and will still be called by Jackson. The {@link JsonProperty} can
         * got on the getter or setter and still work.
         *
         * @param hooks
         *            list of hooks
         */
        private void setHooks(List<String> hooks) {
            this.hooks = hooks;
        }

        private void setVerifiablePasswordAuthentication(boolean verifiablePasswordAuthentication) {
            this.verifiablePasswordAuthentication = verifiablePasswordAuthentication;
        }

        void setApi(List<String> api) {
            this.api = api;
        }

        /**
         * Since we mostly use Jackson for deserialization, {@link JsonSetter} is also okay, but {@link JsonProperty} is
         * preferred.
         *
         * @param git
         *            list of git addresses
         */
        @JsonSetter
        void setGit(List<String> git) {
            this.git = git;
        }

        /**
         * Missing {@link JsonProperty} or having it on the field will cause Jackson to ignore getters and setters.
         *
         * @param importer
         *            list of importer addresses
         */
        void setImporter(List<String> importer) {
            this.importer = importer;
        }

        void setPages(List<String> pages) {
            this.pages = pages;
        }

        /**
         * The {@link JsonProperty} can got on the getter or setter and still work.
         *
         * @param web
         *            list of web addresses
         */
        void setWeb(List<String> web) {
            this.web = web;
        }

    }

    /**
     * This version uses public getters and setters and leaves it up to Jackson how it wants to fill them.
     * <p>
     * Pro:
     * <ul>
     * <li>Easy to create</li>
     * <li>Not much code</li>
     * <li>Minimal annotations</li>
     * </ul>
     * Con:
     * <ul>
     * <li>Exposes public setters for fields that should not be changed, flagged by spotbugs</li>
     * <li>Lists modifiable when they should not be changed</li>
     * <li>Jackson generally doesn't call the setters, it just sets the fields directly</li>
     * </ul>
     *
     * @author Paulo Miguel Almeida
     * @see org.kohsuke.github.GHMeta
     */
    public static class GHMetaPublic implements GHMetaExample {

        private List<String> api;

        private List<String> git;
        private List<String> hooks;
        private List<String> importer;
        private List<String> pages;
        @JsonProperty("verifiable_password_authentication")
        private boolean verifiablePasswordAuthentication;
        private List<String> web;
        /**
         * Create default GHMetaPublic instance
         */
        public GHMetaPublic() {
        }

        @SuppressFBWarnings(value = { "EI_EXPOSE_REP" }, justification = "Noted above")
        public List<String> getApi() {
            return api;
        }

        @SuppressFBWarnings(value = { "EI_EXPOSE_REP" }, justification = "Noted above")
        public List<String> getGit() {
            return git;
        }

        @SuppressFBWarnings(value = { "EI_EXPOSE_REP" }, justification = "Noted above")
        public List<String> getHooks() {
            return hooks;
        }

        @SuppressFBWarnings(value = { "EI_EXPOSE_REP" }, justification = "Noted above")
        public List<String> getImporter() {
            return importer;
        }

        @SuppressFBWarnings(value = { "EI_EXPOSE_REP" }, justification = "Noted above")
        public List<String> getPages() {
            return pages;
        }

        @SuppressFBWarnings(value = { "EI_EXPOSE_REP" }, justification = "Noted above")
        public List<String> getWeb() {
            return web;
        }

        public boolean isVerifiablePasswordAuthentication() {
            return verifiablePasswordAuthentication;
        }

        /**
         * Sets api.
         *
         * @param api
         *            the api
         */
        @SuppressFBWarnings(value = { "EI_EXPOSE_REP2" }, justification = "Spotbugs also doesn't like this")
        public void setApi(List<String> api) {
            this.api = api;
        }

        /**
         * Sets git.
         *
         * @param git
         *            the git
         */
        @SuppressFBWarnings(value = { "EI_EXPOSE_REP2" }, justification = "Spotbugs also doesn't like this")
        public void setGit(List<String> git) {
            this.git = git;
        }

        /**
         * Sets hooks.
         *
         * @param hooks
         *            the hooks
         */
        @SuppressFBWarnings(value = { "EI_EXPOSE_REP2" }, justification = "Spotbugs also doesn't like this")
        public void setHooks(List<String> hooks) {
            this.hooks = hooks;
        }

        /**
         * Sets importer.
         *
         * @param importer
         *            the importer
         */
        @SuppressFBWarnings(value = { "EI_EXPOSE_REP2" }, justification = "Spotbugs also doesn't like this")
        public void setImporter(List<String> importer) {
            this.importer = importer;
        }

        /**
         * Sets pages.
         *
         * @param pages
         *            the pages
         */
        @SuppressFBWarnings(value = { "EI_EXPOSE_REP2" }, justification = "Spotbugs also doesn't like this")
        public void setPages(List<String> pages) {
            this.pages = pages;
        }

        /**
         * Sets verifiable password authentication.
         *
         * @param verifiablePasswordAuthentication
         *            the verifiable password authentication
         */
        public void setVerifiablePasswordAuthentication(boolean verifiablePasswordAuthentication) {
            this.verifiablePasswordAuthentication = verifiablePasswordAuthentication;
        }

        /**
         * Sets web.
         *
         * @param web
         *            the web
         */
        @SuppressFBWarnings(value = { "EI_EXPOSE_REP2" }, justification = "Spotbugs also doesn't like this")
        public void setWeb(List<String> web) {
            this.web = web;
        }

    }

    /**
     * Placeholder constructor.
     */
    public ReadOnlyObjects() {
    }
}