From 1763fee28eea120a3dd6a561b0654472585e30c5 Mon Sep 17 00:00:00 2001 From: Oleg Nenashev Date: Sat, 14 Mar 2020 10:27:08 +0100 Subject: [PATCH] =?UTF-8?q?Document=20nullability=20of=20newInstanceFromRa?= =?UTF-8?q?dioList()=20methods=20and=E2=80=A6=20(#4543)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../java/hudson/DescriptorExtensionList.java | 22 +++++++++++++++---- .../main/java/hudson/util/DescriptorList.java | 6 +++-- core/src/main/java/jenkins/model/Jenkins.java | 14 ++++++++++-- 3 files changed, 34 insertions(+), 8 deletions(-) diff --git a/core/src/main/java/hudson/DescriptorExtensionList.java b/core/src/main/java/hudson/DescriptorExtensionList.java index 7682e90e2c..acc12df9b8 100644 --- a/core/src/main/java/hudson/DescriptorExtensionList.java +++ b/core/src/main/java/hudson/DescriptorExtensionList.java @@ -46,6 +46,7 @@ import java.util.logging.Level; import java.util.logging.Logger; import java.util.concurrent.CopyOnWriteArrayList; import javax.annotation.CheckForNull; +import javax.annotation.Nonnull; import net.sf.json.JSONException; import org.kohsuke.stapler.Stapler; @@ -133,10 +134,14 @@ public class DescriptorExtensionList, D extends Descrip } /** - * Creates a new instance of a {@link Describable} - * from the structured form submission data posted - * by a radio button group. + * Creates a new instance of a {@link Describable} from the structured form submission data posted by a radio button group. + * @param config Submitted configuration for Radio List + * @return New instance. + * {@code null} if none was selected in the radio list or if the value is filtered by a {@link hudson.model.DescriptorVisibilityFilter} + * @throws FormException Data submission error + * @since 1.312 */ + @CheckForNull public T newInstanceFromRadioList(JSONObject config) throws FormException { if(config.isNullObject()) return null; // none was selected @@ -144,7 +149,16 @@ public class DescriptorExtensionList, D extends Descrip return get(idx).newInstance(Stapler.getCurrentRequest(),config); } - public T newInstanceFromRadioList(JSONObject parent, String name) throws FormException { + /** + * Creates a new instance of a {@link Describable} from the structured form submission data posted by a radio list. + * @since 1.312 + * @param name Name of the form field + * @return Created instance. + * {@code null} if none was selected in the radio list or if the value is filtered by a {@link hudson.model.DescriptorVisibilityFilter} + * @throws FormException Data submission error + */ + @CheckForNull + public T newInstanceFromRadioList(@Nonnull JSONObject parent, @Nonnull String name) throws FormException { try { return newInstanceFromRadioList(parent.getJSONObject(name)); } catch (JSONException ex) { diff --git a/core/src/main/java/hudson/util/DescriptorList.java b/core/src/main/java/hudson/util/DescriptorList.java index 544ab12509..2ade0531ca 100644 --- a/core/src/main/java/hudson/util/DescriptorList.java +++ b/core/src/main/java/hudson/util/DescriptorList.java @@ -151,7 +151,8 @@ public final class DescriptorList> extends AbstractList * from the structured form submission data posted * by a radio button group. * @param config Submitted configuration for Radio List - * @return new instance or {@code null} if none was selected in the radio list + * @return New instance. + * {@code null} if none was selected in the radio list or if the value is filtered by a {@link hudson.model.DescriptorVisibilityFilter} * @throws FormException Data submission error */ @CheckForNull @@ -168,7 +169,8 @@ public final class DescriptorList> extends AbstractList * by a radio button group. * @param parent JSON, which contains the configuration entry for the radio list * @param name Name of the configuration entry for the radio list - * @return new instance or {@code null} if none was selected in the radio list + * @return New instance. + * {@code null} if none was selected in the radio list or if the value is filtered by a {@link hudson.model.DescriptorVisibilityFilter} * @throws FormException Data submission error */ @CheckForNull diff --git a/core/src/main/java/jenkins/model/Jenkins.java b/core/src/main/java/jenkins/model/Jenkins.java index 14ed4892d6..f843b08844 100644 --- a/core/src/main/java/jenkins/model/Jenkins.java +++ b/core/src/main/java/jenkins/model/Jenkins.java @@ -2604,7 +2604,12 @@ public class Jenkins extends AbstractCIBase implements DirectlyModifiableTopLeve return securityRealm; } - public void setSecurityRealm(SecurityRealm securityRealm) { + /** + * Sets a security realm. + * @param securityRealm Security realm to set. + * If {@code null}, {@link SecurityRealm#NO_AUTHENTICATION} will be set. + */ + public void setSecurityRealm(@CheckForNull SecurityRealm securityRealm) { if(securityRealm==null) securityRealm= SecurityRealm.NO_AUTHENTICATION; this.useSecurity = true; @@ -2634,7 +2639,12 @@ public class Jenkins extends AbstractCIBase implements DirectlyModifiableTopLeve saveQuietly(); } - public void setAuthorizationStrategy(AuthorizationStrategy a) { + /** + * Sets a new authorization strategy. + * @param a Authorization strategy to set. + * If {@code null}, {@link AuthorizationStrategy#UNSECURED} will be set + */ + public void setAuthorizationStrategy(@CheckForNull AuthorizationStrategy a) { if (a == null) a = AuthorizationStrategy.UNSECURED; useSecurity = true; -- GitLab