[ENG-10291] Update the institution model to support in-progress SSO (#106)

* Add `SsoAvailability` enum and update `institution` model
* Fix JavaDoc and style

Author: cslzchen

src/main/java/io/cos/cas/osf/authentication/support/SsoAvailability.java

@@ -0,0 +1,46 @@
+package io.cos.cas.osf.authentication.support;
+
+/**
+ * This is {@link SsoAvailability}.
+ *
+ * @author Longze Chen
+ * @since 26.1.0
+ */
+public enum SsoAvailability {
+
+    /**
+     * The institution is active, has a delegation protocol, and its SSO setup has been verified.
+     * */
+    PUBLIC("Public"),
+    /**
+     * The institution is either: 1) inactive and has a delegation protocol,
+     * or 2) active, has a delegation protocol but its SSO setup is in-progress.
+     */
+    HIDDEN("Hidden"),
+    /**
+     * The institution does not have a delegation protocol (i.e. not eligible for SSO).
+     */
+    UNAVAILABLE("Unavailable");
+
+    private final String id;
+
+    SsoAvailability(final String id) {
+        this.id = id;
+    }
+
+    public static SsoAvailability getType(final String id) throws IllegalArgumentException {
+        if (id == null) {
+            return null;
+        }
+        for (final SsoAvailability type : SsoAvailability.values()) {
+            if (id.equals(type.getId())) {
+                return type;
+            }
+        }
+        throw new IllegalArgumentException("No matching type for id " + id);
+    }
+
+    public final String getId() {
+        return id;
+    }
+}

src/main/java/io/cos/cas/osf/model/OsfInstitution.java

@@ -1,6 +1,7 @@
 package io.cos.cas.osf.model;
 
 import io.cos.cas.osf.authentication.support.DelegationProtocol;
+import io.cos.cas.osf.authentication.support.SsoAvailability;
 
 import lombok.Getter;
 import lombok.NoArgsConstructor;
@@ -14,7 +15,8 @@
 import java.util.Date;
 
 /**
- * This is {@link OsfInstitution}.
+ * This is {@link OsfInstitution}. It maps to a subset of columns in the OSF DB table {@code osf_instittuion}.
+ * This subset is required to support institution SSO for CAS and OSF.
  *
  * @author Longze Chen
  * @since 21.0.0
@@ -40,27 +42,47 @@ public class OsfInstitution extends AbstractOsfModel {
     @Column(name = "logout_url")
     private String logoutUrl;
 
+    /**
+     * Maps to column {@code delegation_protocol} of table {@code osf_instittuion} in OSF database.
+     */
     @Column(name = "delegation_protocol")
     private String delegationProtocol;
 
+    /**
+     * Maps to column {@code sso_availability} of table {@code osf_instittuion} in OSF database.
+     */
+    @Column(name = "sso_availability")
+    private String ssoAvailability;
+
     @Column(name = "is_deleted")
     private Boolean deleted;
 
-    @Column(name = "sso_in_progress")
-    private Boolean ssoInProgress;
-
     @Temporal(TemporalType.TIMESTAMP)
     @Column(name = "deactivated")
     private Date dateDeactivated;
 
     @Column(name = "support_email", nullable = false)
     private String supportEmail;
 
+    /**
+     * @return the institution's delegation protocol.
+     */
     public DelegationProtocol getDelegationProtocol() {
         try {
             return DelegationProtocol.getType(delegationProtocol);
         } catch (final IllegalArgumentException e) {
             return null;
         }
     }
+
+    /**
+     * @return the institution's SSO Availability.
+     */
+    public SsoAvailability getSsoAvailability() {
+        try {
+            return SsoAvailability.getType(ssoAvailability);
+        } catch (final IllegalArgumentException e) {
+            return null;
+        }
+    }
 }