Add validation for Element.id and Extension.url

These elements are "special" in that, in the XML serialization, they are
attributes and not elements.
To facilitate this "specialness", we keep them as raw java strings in
our model, but according to the spec they should still be valid data
types (String and Id respectively).

Also added javadoc for ValidationSupport.java

Signed-off-by: Lee Surprenant <lmsurpre@us.ibm.com>

Author: lmsurpre

fhir-model/src/main/java/com/ibm/fhir/model/type/Element.java

@@ -37,6 +37,7 @@ public abstract class Element extends AbstractVisitable {
     protected Element(Builder builder) {
         id = builder.id;
         extension = Collections.unmodifiableList(ValidationSupport.requireNonNull(builder.extension, "extension"));
+        ValidationSupport.checkString(id);
     }
 
     /**

fhir-model/src/main/java/com/ibm/fhir/model/type/Extension.java

@@ -40,6 +40,7 @@ private Extension(Builder builder) {
         super(builder);
         url = ValidationSupport.requireNonNull(builder.url, "url");
         value = ValidationSupport.choiceElement(builder.value, "value", Base64Binary.class, Boolean.class, Canonical.class, Code.class, Date.class, DateTime.class, Decimal.class, Id.class, Instant.class, Integer.class, Markdown.class, Oid.class, PositiveInt.class, String.class, Time.class, UnsignedInt.class, Uri.class, Url.class, Uuid.class, Address.class, Age.class, Annotation.class, Attachment.class, CodeableConcept.class, Coding.class, ContactPoint.class, Count.class, Distance.class, Duration.class, HumanName.class, Identifier.class, Money.class, Period.class, Quantity.class, Range.class, Ratio.class, Reference.class, SampledData.class, Signature.class, Timing.class, ContactDetail.class, Contributor.class, DataRequirement.class, Expression.class, ParameterDefinition.class, RelatedArtifact.class, TriggerDefinition.class, UsageContext.class, Dosage.class);
+        ValidationSupport.checkUri(url);
         ValidationSupport.requireValueOrChildren(this);
     }
 

fhir-model/src/main/java/com/ibm/fhir/model/type/Id.java

@@ -8,7 +8,6 @@
 
 import java.util.Collection;
 import java.util.Objects;
-import java.util.regex.Pattern;
 
 import javax.annotation.Generated;
 
@@ -21,13 +20,11 @@
  */
 @Generated("com.ibm.fhir.tools.CodeGenerator")
 public class Id extends String {
-    private static final Pattern PATTERN = Pattern.compile("[A-Za-z0-9\\-\\.]{1,64}");
-
     private volatile int hashCode;
 
     private Id(Builder builder) {
         super(builder);
-        ValidationSupport.checkValue(value, PATTERN);
+        ValidationSupport.checkId(value);
     }
 
     @Override

fhir-model/src/main/java/com/ibm/fhir/model/util/ValidationSupport.java

@@ -24,8 +24,11 @@
 import com.ibm.fhir.model.resource.Resource;
 import com.ibm.fhir.model.type.Element;
 
-public final class ValidationSupport {    
-    private static final int MIN_LENGTH = 1;
+/**
+ * Static helper methods for validating model objects during construction
+ */
+public final class ValidationSupport {
+    private static final int MIN_STRING_LENGTH = 1;
     private static final int MAX_STRING_LENGTH = 1048576; // 1024 * 1024 = 1MB
     private static final String FHIR_XHTML_XSD = "fhir-xhtml.xsd";
     private static final String FHIR_XML_XSD = "xml.xsd";
@@ -42,6 +45,17 @@ public Validator initialValue() {
     private ValidationSupport() { }
 
     private static final Set<Character> WHITESPACE = new HashSet<>(Arrays.asList(' ', '\t', '\r', '\n'));
+    
+    /**
+     * A sequence of Unicode characters
+     * <pre>
+     * pattern:  [ \r\n\t\S]+
+     * </pre>
+     * 
+     * @throws IllegalStateException if the passed String is not a valid FHIR String value
+     * @apiNote IllegalStateException is chosen in favor of IllegalArgumentException so that Builder.build()
+     *          methods can throw the most appropriate exception without catching and wrapping.
+     */
     public static void checkString(String s) {
         if (s == null) {
             return;
@@ -59,11 +73,22 @@ public static void checkString(String s) {
                 throw new IllegalStateException(String.format("String value: '%s' is not valid with respect to pattern: [ \\r\\n\\t\\S]+", s));
             }
         }
-        if (count < MIN_LENGTH) {
-            throw new IllegalStateException(String.format("Trimmed String value length: %d is less than minimum required length: %d", count, MIN_LENGTH));
+        if (count < MIN_STRING_LENGTH) {
+            throw new IllegalStateException(String.format("Trimmed String value length: %d is less than minimum required length: %d", count, MIN_STRING_LENGTH));
         }
     }
 
+    /**
+     * A string which has at least one character and no leading or trailing whitespace and where there is no whitespace other 
+     * than single spaces in the contents.
+     * <pre>
+     * pattern:  [^\s]+(\s[^\s]+)*
+     * </pre>
+     * 
+     * @throws IllegalStateException if the passed String is not a valid FHIR Code value
+     * @apiNote IllegalStateException is chosen in favor of IllegalArgumentException so that Builder.build()
+     *          methods can throw the most appropriate exception without catching and wrapping.
+     */
     public static void checkCode(String s) {
         if (s == null) {
             return;
@@ -93,6 +118,54 @@ public static void checkCode(String s) {
         }
     }
 
+    /**
+     * Any combination of letters, numerals, "-" and ".", with a length limit of 64 characters. (This might be an integer, an 
+     * unprefixed OID, UUID or any other identifier pattern that meets these constraints.) Ids are case-insensitive.
+     * <pre>
+     * pattern:  [A-Za-z0-9\-\.]{1,64}
+     * </pre>
+     * 
+     * @throws IllegalStateException if the passed String is not a valid FHIR Id value
+     * @apiNote IllegalStateException is chosen in favor of IllegalArgumentException so that Builder.build()
+     *          methods can throw the most appropriate exception without catching and wrapping.
+     */
+    public static void checkId(String s) {
+        if (s == null) {
+            return;
+        }
+        if (s.isEmpty()) {
+            throw new IllegalStateException(String.format("Id value must not be empty"));
+        }
+        if (s.length() > 64) {
+            throw new IllegalStateException(String.format("Id value length: %d is greater than maximum allowed length: %d", s.length(), 64));
+        }
+
+        for (int i = 0; i < s.length(); i++) {
+            char c = s.charAt(i);
+            //45 = '-'
+            //46 = '.'
+            //48 = '0'
+            //57 = '9'
+            //65 = 'A'
+            //90 = 'Z'
+            //97 = 'a'
+            //122 = 'z'
+            if (c < 45 || c == 47 || (c > 57 && c < 65) || (c > 90 && c < 97) || c > 122 ) {
+                throw new IllegalStateException(String.format("Id value: '%s' contain invalid character '%s'", s, c));
+            }
+        }
+    }
+    
+    /**
+     * String of characters used to identify a name or a resource
+     * <pre>
+     * pattern:  \S*
+     * </pre>
+     * 
+     * @throws IllegalStateException if the passed String is not a valid FHIR Id value
+     * @apiNote IllegalStateException is chosen in favor of IllegalArgumentException so that Builder.build()
+     *          methods can throw the most appropriate exception without catching and wrapping.
+     */
     public static void checkUri(String s) {
         if (s == null) {
             return;
@@ -108,6 +181,11 @@ public static void checkUri(String s) {
         }
     }
 
+    /**
+     * @throws IllegalStateException if the passed String is longer than the maximum string length
+     * @apiNote IllegalStateException is chosen in favor of IllegalArgumentException so that Builder.build()
+     *          methods can throw the most appropriate exception without catching and wrapping.
+     */
     public static void checkMaxLength(String value) {
         if (value != null) {
             if (value.length() > MAX_STRING_LENGTH) {
@@ -116,14 +194,24 @@ public static void checkMaxLength(String value) {
         }
     }
 
+    /**
+     * @throws IllegalStateException if the passed String is shorter than the minimum string length
+     * @apiNote IllegalStateException is chosen in favor of IllegalArgumentException so that Builder.build()
+     *          methods can throw the most appropriate exception without catching and wrapping.
+     */
     public static void checkMinLength(String value) {
         if (value != null) {
-            if (value.trim().length() < MIN_LENGTH) {
-                throw new IllegalStateException(String.format("String value length: %d is less than minimum required length: %d", value.trim().length(), MIN_LENGTH));
+            if (value.trim().length() < MIN_STRING_LENGTH) {
+                throw new IllegalStateException(String.format("Trimmed String value length: %d is less than minimum required length: %d", value.trim().length(), MIN_STRING_LENGTH));
             }
         }
     }
 
+    /**
+     * @throws IllegalStateException if the passed Integer value is less than the passed minValue
+     * @apiNote IllegalStateException is chosen in favor of IllegalArgumentException so that Builder.build()
+     *          methods can throw the most appropriate exception without catching and wrapping.
+     */
     public static void checkValue(Integer value, int minValue) {
         if (value != null) {
             if (value < minValue) {
@@ -132,6 +220,11 @@ public static void checkValue(Integer value, int minValue) {
         }
     }
 
+    /**
+     * @throws IllegalStateException if the passed String value does not match the passed pattern
+     * @apiNote IllegalStateException is chosen in favor of IllegalArgumentException so that Builder.build()
+     *          methods can throw the most appropriate exception without catching and wrapping.
+     */
     public static void checkValue(String value, Pattern pattern) {
         if (value != null) {
             if (!pattern.matcher(value).matches()) {
@@ -140,6 +233,11 @@ public static void checkValue(String value, Pattern pattern) {
         }
     }
 
+    /**
+     * @throws IllegalStateException if the type of the passed value is not one of the passed types
+     * @apiNote IllegalStateException is chosen in favor of IllegalArgumentException so that Builder.build()
+     *          methods can throw the most appropriate exception without catching and wrapping.
+     */
     public static <T> T checkValueType(T value, Class<?>... types) {
         if (value != null) {
             List<Class<?>> typeList = Arrays.asList(types);
@@ -151,17 +249,13 @@ public static <T> T checkValueType(T value, Class<?>... types) {
         }
         return value;
     }
-        
-    public static void checkXHTMLContent(String value) {
-        try {
-            Validator validator = THREAD_LOCAL_VALIDATOR.get();
-            validator.reset();
-            validator.validate(new StreamSource(new StringReader(value)));
-        } catch (Exception e) {
-            throw new IllegalStateException(String.format("Invalid XHTML content: %s", e.getMessage()), e);
-        }
-    }
-    
+
+    /**
+     * @throws IllegalStateException if the type of the passed element is not one of the passed types
+     * @apiNote IllegalStateException is chosen in favor of IllegalArgumentException so that Builder.build()
+     *          methods can throw the most appropriate exception without catching and wrapping.
+     * @apiNote Only differs from {@link #checkValueType} in that we can provide a better error message
+     */
     public static <T extends Element> T choiceElement(T element, String elementName, Class<?>... types) {
         if (element != null) {
             Class<?> elementType = element.getClass();
@@ -172,7 +266,22 @@ public static <T extends Element> T choiceElement(T element, String elementName,
         }
         return element;
     }
-    
+
+    /**
+     * @throws IllegalStateException if the passed String value is not valid XHTML
+     * @apiNote IllegalStateException is chosen in favor of IllegalArgumentException so that Builder.build()
+     *          methods can throw the most appropriate exception without catching and wrapping.
+     */
+    public static void checkXHTMLContent(String value) {
+        try {
+            Validator validator = THREAD_LOCAL_VALIDATOR.get();
+            validator.reset();
+            validator.validate(new StreamSource(new StringReader(value)));
+        } catch (Exception e) {
+            throw new IllegalStateException(String.format("Invalid XHTML content: %s", e.getMessage()), e);
+        }
+    }
+
     private static Schema createSchema() {
         try {
             StreamSource[] sources = new StreamSource[3];
@@ -195,11 +304,21 @@ private static SchemaFactory createSchemaFactory() {
         }
     }
 
+    /**
+     * @throws IllegalStateException if the passed element is null or if its type is not one of the passed types
+     * @apiNote IllegalStateException is chosen in favor of IllegalArgumentException so that Builder.build()
+     *          methods can throw the most appropriate exception without catching and wrapping.
+     */
     public static <T extends Element> T requireChoiceElement(T element, String elementName, Class<?>... types) {
         requireNonNull(element, elementName);
         return choiceElement(element, elementName, types);
     }
 
+    /**
+     * @throws IllegalStateException if the passed list is empty or contains any null objects
+     * @apiNote IllegalStateException is chosen in favor of IllegalArgumentException so that Builder.build()
+     *          methods can throw the most appropriate exception without catching and wrapping.
+     */
     public static <T> List<T> requireNonEmpty(List<T> elements, String elementName) {
         requireNonNull(elements, elementName);
         if (elements.isEmpty()) {
@@ -208,38 +327,68 @@ public static <T> List<T> requireNonEmpty(List<T> elements, String elementName)
         return elements;
     }
 
+    /**
+     * @throws IllegalStateException if the passed element is null
+     * @apiNote IllegalStateException is chosen in favor of IllegalArgumentException so that Builder.build()
+     *          methods can throw the most appropriate exception without catching and wrapping.
+     */
     public static <T> T requireNonNull(T element, String elementName) {
         if (element == null) {
             throw new IllegalStateException(String.format("Missing required element: '%s'", elementName));
         }
         return element;
     }
 
+    /**
+     * @throws IllegalStateException if the passed list contains any null objects
+     * @apiNote IllegalStateException is chosen in favor of IllegalArgumentException so that Builder.build()
+     *          methods can throw the most appropriate exception without catching and wrapping.
+     */
     public static <T> List<T> requireNonNull(List<T> elements, String elementName) {
         if (elements.stream().anyMatch(Objects::isNull)) {
             throw new IllegalStateException(String.format("Repeating element: '%s' does not permit null elements", elementName));
         }
         return elements;
     }
 
+    /**
+     * @throws IllegalStateException if the passed element has no value and no children
+     * @apiNote IllegalStateException is chosen in favor of IllegalArgumentException so that Builder.build()
+     *          methods can throw the most appropriate exception without catching and wrapping.
+     */
     public static void requireValueOrChildren(Element element) {
         if (!element.hasValue() && !element.hasChildren()) {
             throw new IllegalStateException("ele-1: All FHIR elements must have a @value or children");
         }
     }
 
+    /**
+     * @throws IllegalStateException if the passed element has no children
+     * @apiNote IllegalStateException is chosen in favor of IllegalArgumentException so that Builder.build()
+     *          methods can throw the most appropriate exception without catching and wrapping.
+     */
     public static void requireChildren(Resource resource) {
         if (!resource.hasChildren()) {
             throw new IllegalStateException("global-1: All FHIR elements must have a @value or children");
         }
     }
 
+    /**
+     * @throws IllegalStateException if the passed element is not null
+     * @apiNote IllegalStateException is chosen in favor of IllegalArgumentException so that Builder.build()
+     *          methods can throw the most appropriate exception without catching and wrapping.
+     */
     public static void prohibited(Element element, String elementName) {
         if (element != null) {
             throw new IllegalStateException(String.format("Element: '%s' is prohibited.", elementName));
         }
     }
 
+    /**
+     * @throws IllegalStateException if the passed list is not empty
+     * @apiNote IllegalStateException is chosen in favor of IllegalArgumentException so that Builder.build()
+     *          methods can throw the most appropriate exception without catching and wrapping.
+     */
     public static <T extends Element> void prohibited(List<T> elements, String elementName) {
         if (!elements.isEmpty()) {
             throw new IllegalStateException(String.format("Element: '%s' is prohibited.", elementName));