001package org.hl7.fhir.utilities;
002
003import java.util.*;
004
005import org.apache.commons.lang3.StringUtils;
006import org.hl7.fhir.exceptions.FHIRException;
007
008import javax.annotation.Nonnull;
009import javax.annotation.Nullable;
010
011/*
012  Copyright (c) 2011+, HL7, Inc.
013  All rights reserved.
014
015  Redistribution and use in source and binary forms, with or without modification, 
016  are permitted provided that the following conditions are met:
017
018 * Redistributions of source code must retain the above copyright notice, this 
019     list of conditions and the following disclaimer.
020 * Redistributions in binary form must reproduce the above copyright notice, 
021     this list of conditions and the following disclaimer in the documentation 
022     and/or other materials provided with the distribution.
023 * Neither the name of HL7 nor the names of its contributors may be used to 
024     endorse or promote products derived from this software without specific 
025     prior written permission.
026
027  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 
028  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
029  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 
030  IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 
031  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 
032  NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 
033  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
034  WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
035  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
036  POSSIBILITY OF SUCH DAMAGE.
037
038 */
039
040
041public class VersionUtilities {
042
043  public enum VersionPrecision { MAJOR, MINOR, PATCH, FULL}
044
045  public static class SemVerSorter implements Comparator<String> {
046
047    @Override
048    public int compare(String s1, String s2) {
049      return compareVersions(s1, s2);
050    }
051
052  }
053
054  public static class SemVer {
055    private String major;
056    private String minor;
057    private String patch;
058    private String label;
059
060    public SemVer(String ver) {
061      String[] p = ver.split("\\.");
062      if (p.length > 0) {
063        major = p[0];
064      }
065      if (p.length > 1) {
066        minor = p[1];
067      }
068      if (p.length > 2) {
069        patch = p[2];
070        if (patch.contains("-")) {
071          label = patch.substring(patch.indexOf("-") + 1);
072          patch = patch.substring(0, patch.indexOf("-"));
073        }
074      }
075    }
076
077    private int compareString(String s1, String s2) {
078      if (s1 == null) {
079        return s2 == null ? 0 : 1;
080      } else if (s2 == null) {
081        return -1;
082      } else {
083        return s1.compareTo(s2);
084      }
085    }
086
087
088    private int compareInteger(String s1, String s2) {
089      if (s1 == null) {
090        return s2 == null ? 0 : 1;
091      } else if (s2 == null) {
092        return -1;
093      } else {
094        return Integer.compare(Integer.parseInt(s1), Integer.parseInt(s2));
095      }
096    }
097
098    public int compareTo(SemVer sv2) {
099      int c = compareInteger(major, sv2.major);
100      if (c == 0) {
101        c = compareInteger(minor, sv2.minor);
102      }
103      if (c == 0) {
104        c = compareInteger(patch, sv2.patch);
105      }
106      if (c == 0) {
107        c = compareString(label, sv2.label);
108      }
109      return c;
110    }
111
112  }
113
114  public static final String[] SUPPORTED_MAJOR_VERSIONS = {"1.0", "1.4", "3.0", "4.0", "5.0", "6.0"};
115  public static final String[] SUPPORTED_VERSIONS = {"1.0.2", "1.4.0", "3.0.2", "4.0.1", "4.1.0", "4.3.0", "5.0.0", "6.0.0"};
116
117  public static class VersionURLInfo {
118    private String version;
119    private String url;
120
121    public VersionURLInfo(String version, String url) {
122      super();
123      this.version = version;
124      this.url = url;
125    }
126
127    public String getVersion() {
128      return version;
129    }
130
131    public String getUrl() {
132      return url;
133    }
134  }
135
136  /**
137   * Returns the package name for the given FHIR version.
138   * @param v FHIR version string
139   * @return package name (e.g., "hl7.fhir.r4.core") or null if version not recognized
140   */
141  public @Nonnull static String packageForVersion(@Nonnull String v) {
142    if (isR2Ver(v)) {
143      return "hl7.fhir.r2.core";
144    }
145    if (isR2BVer(v)) {
146      return "hl7.fhir.r2b.core";
147    }
148    if (isR3Ver(v)) {
149      return "hl7.fhir.r3.core";
150    }
151    if (isR4Ver(v)) {
152      return "hl7.fhir.r4.core";
153    }
154
155    if (isR4BVer(v)) {
156      return "hl7.fhir.r4b.core";
157    }
158
159    if (isR5Ver(v)) {
160      return "hl7.fhir.r5.core";
161    }
162
163    if (isR6Ver(v)) {
164      return "hl7.fhir.r6.core";
165    }
166
167    if ("current".equals(v)) {
168      return "hl7.fhir.r5.core";
169    }
170
171    return null;
172  }
173
174  /**
175   * Returns the current/latest version for a given FHIR version family.
176   * @param v FHIR version string
177   * @return current version string for that family
178   */
179  public static String getCurrentVersion(String v) {
180    if (isR2Ver(v)) {
181      return "1.0.2";
182    }
183    if (isR2BVer(v)) {
184      return "1.4.0";
185    }
186    if (isR3Ver(v)) {
187      return "3.0.2";
188    }
189    if (isR4Ver(v)) {
190      return "4.0.1";
191    }
192    if (isR4BVer(v)) {
193      return "4.3.0";
194    }
195    if (isR5Ver(v)) {
196      return "5.0.0";
197    }
198    if (isR6Ver(v)) {
199      return "6.0.0";
200    }
201    return v;
202  }
203
204  /**
205   * Returns the current package version for a given FHIR version family.
206   * @param v FHIR version string
207   * @return package version (major.minor format)
208   */
209  public static String getCurrentPackageVersion(String v) {
210    if (isR2Ver(v)) {
211      return "1.0";
212    }
213    if (isR2BVer(v)) {
214      return "1.4";
215    }
216    if (isR3Ver(v)) {
217      return "3.0";
218    }
219    if (isR4Ver(v)) {
220      return "4.0";
221    }
222    if (isR5Ver(v)) {
223      return "5.0";
224    }
225    if (isR6Ver(v)) {
226      return "6.0";
227    }
228    return v;
229  }
230
231  /**
232   * Checks if the given version is in the list of supported FHIR versions.
233   * @param version version string to check
234   * @return true if version is supported
235   */
236  public static boolean isSupportedVersion(@Nonnull String version) {
237    version = checkVersionNotNullAndValid(removeLabels(fixForSpecialValue(version)));
238    return Utilities.existsInList(version, SUPPORTED_VERSIONS);
239  }
240
241  /**
242   * Returns a comma-separated list of all supported FHIR versions.
243   * @return string listing supported versions
244   */
245  public static String listSupportedVersions() {
246    return listVersions(SUPPORTED_VERSIONS);
247  }
248
249  /**
250   * Returns a comma-separated list of all supported major FHIR versions.
251   * @return string listing supported major versions
252   */
253  public static String listSupportedMajorVersions() {
254    return listVersions(SUPPORTED_MAJOR_VERSIONS);
255  }
256
257  private static String listVersions(String[] versions) {
258    StringJoiner stringJoiner = new StringJoiner(", ");
259    for (String supportedVersion : versions) {
260      stringJoiner.add(supportedVersion);
261    }
262    return stringJoiner.toString();
263  }
264
265  /**
266   * returns true if version refers to any R6 release (including rX/RX variants)
267   */
268  public static boolean isR6Plus(String version) {
269    return isR6Ver(version);
270  }
271
272  /**
273   * Checks if version refers to any R6 release.
274   * @param version version string to check
275   * @return true if R6 version
276   */
277  public static boolean isR6Ver(@Nonnull String version) {
278    version = removeLabels(checkVersionValidWildcards(fixForSpecialValue(version)));
279    return version != null && (version.startsWith("6.0"));
280  }
281
282  /**
283   * returns true if version refers to any R5 release (including pre-release versions starting from 4.5) (including rX/RX variants)
284   */
285  public static boolean isR5Plus(String version) {
286    return isR5Ver(version) || isR6Plus(version);
287  }
288
289  /**
290   * Checks if version refers to any R5 release (including 4.5+ pre-releases).
291   * @param version version string to check
292   * @return true if R5 version
293   */
294  public static boolean isR5Ver(@Nonnull String version) {
295    version = removeLabels(checkVersionValidWildcards(fixForSpecialValue(version)));
296    return version != null && (version.startsWith("4.5") || version.startsWith("5.0"));
297  }
298
299  /**
300   * Checks if version refers to any R4B release.
301   * @param version version string to check
302   * @return true if R4B version
303   */
304  public static boolean isR4BVer(@Nonnull String version) {
305    version = removeLabels(checkVersionValidWildcards(fixForSpecialValue(version)));
306    return version != null && (version.startsWith("4.1") || version.startsWith("4.3"));
307  }
308
309  /**
310   * Checks if version refers to any R4 release (including 3.2+ pre-releases).
311   * @param version version string to check
312   * @return true if R4 version
313   */
314  public static boolean isR4Ver(@Nonnull String version) {
315    version = removeLabels(checkVersionValidWildcards(fixForSpecialValue(version)));
316    return version != null && (version.startsWith("4.0")
317      // pre-release versions
318      || version.startsWith("3.2") || version.startsWith("3.3") || version.startsWith("3.5") || version.startsWith("3.5a")); // todo: 3.5a is not legal :-(
319  }
320
321  /**
322   * returns true if version refers to any R4 release (including pre-release versions starting from 3.2) (including rX/RX variants)
323   */
324  public static boolean isR4Plus(String version) {
325    return isR4Ver(version) || isR4BVer(version) || isR5Plus(version);
326  }
327
328  /**
329   * Checks if version refers to any R3 release.
330   * @param version version string to check
331   * @return true if R3 version
332   */
333  public static boolean isR3Ver(@Nonnull String version) {
334    version = removeLabels(checkVersionValidWildcards(fixForSpecialValue(version)));
335    return version != null && (version.startsWith("3.0"));
336  }
337
338  /**
339   * Checks if version refers to any R2B release.
340   * @param version version string to check
341   * @return true if R2B version
342   */
343  public static boolean isR2BVer(@Nonnull String version) {
344    version = removeLabels(checkVersionValidWildcards(fixForSpecialValue(version)));
345    return version != null && (version.startsWith("1.4"));
346  }
347
348  /**
349   * Checks if version refers to any R2 release.
350   * @param version version string to check
351   * @return true if R2 version
352   */
353  public static boolean isR2Ver(@Nonnull String version) {
354    version = removeLabels(checkVersionValidWildcards(fixForSpecialValue(version)));
355    return version != null && (version.startsWith("1.0"));
356  }
357
358  /**
359   * Checks if the given string is a FHIR core package name.
360   * @param s package name to check
361   * @return true if it's a core package
362   */
363  public static boolean isCorePackage(@Nonnull String s) {
364    if (s == null) {
365      return false;
366    }
367    if (s.contains("#")) {
368      s = s.substring(0, s.indexOf("#"));
369    }
370    return Utilities.existsInList(s, "hl7.fhir.core", "hl7.fhir.r2.core", "hl7.fhir.r2b.core", "hl7.fhir.r3.core", "hl7.fhir.r4.core", "hl7.fhir.r4b.core", "hl7.fhir.r5.core", "hl7.fhir.r6.core");
371  }
372
373  /**
374   * Returns version string with labels (pre-release/build info) removed.
375   * @param version version string
376   * @return version without labels, or null if invalid
377   */
378  public static @Nullable String versionWithoutLabels(@Nullable String version) {
379    version = checkVersionNotNullAndValid(fixForSpecialValue(version));
380    return removeLabels(version);
381  }
382
383  /**
384   * given any valid semver string, returns major.minor. Also accepts the special values rX/RX where X is a major FHIR version (2,2B,3,4,4B,5,6)
385   *
386   * returns null if not a valid semver
387   */
388  public static @Nullable String getMajMin(@Nullable String version) {
389    version = removeLabels(fixForSpecialValue(version));
390    if (version == null) {
391      return null;
392    }
393    if (!isSemVer(version)) {
394      return null;
395    }
396    return getMajMinPriv(version);
397  }
398
399  private static String getMajMinPriv(String version) {
400    String[] p = version.split("\\.");
401    return p[0] + "." + p[1];
402  }
403
404  /**
405   * given any valid semver string, returns major.minor.patch. Also accepts the special values rX/RX where X is a major FHIR version (2,2B,3,4,4B,5,6)
406   *
407   * if there's no patch, it will be assumed to be 0
408   *
409   * returns null if it's not a valid semver
410   */
411  public static String getMajMinPatch(@Nullable String version) {
412    version = removeLabels(fixForSpecialValue(version));
413    if (version == null) {
414      return null;
415    }
416    if (!isSemVer(version)) {
417      return null;
418    }
419    String[] p = version.split("\\.");
420    return p[0] + "." + p[1] + (p.length >= 3 ? "." + p[2] : ".0");
421  }
422
423  /**
424   * given any valid semver string, returns just the patch version, with no labels. Also accepts the special values rX/RX where X is a major FHIR version (2,2B,3,4,4B,5,6)
425   */
426  public static String getPatch(@Nullable String version) {
427    version = removeLabels(checkVersionValid(fixForSpecialValue(version)));
428    if (version == null)
429      return null;
430    return getPatchPriv(version);
431  }
432
433  private static String getPatchPriv(String version) {
434    String[] p = version.split("\\.");
435    return p.length >= 3 ? p[2] : "0";
436  }
437
438
439  /**
440   * returns true if this is a valid semver.
441   *
442   * Note that we accept major.minor without a patch (but maybe with labels).
443   *
444   * This routine does not accept the codes such as RX
445   */
446  public static boolean isSemVer(@Nullable String version) {
447    if (Utilities.noString(version)) {
448      return false;
449    }
450    // this used to be done with a regex, but it's actually too complicated to handle the corner cases that way
451    SemverParser.ParseResult pr = SemverParser.parseSemver(version, false, false);
452    if (!pr.isSuccess()) {
453      return false;
454    }
455    return Utilities.isInteger(pr.getMajor()) && Utilities.isInteger(pr.getMinor())
456      && (pr.getPatch() == null || Utilities.isInteger(pr.getPatch()));
457  }
458
459  /**
460   * Checks if version string is valid semver with wildcard support.
461   * @param version version string to validate
462   * @return true if valid semver with wildcards
463   */
464  public static boolean isSemVerWithWildcards(@Nullable String version) {
465    if (Utilities.noString(version)) {
466      return false;
467    }
468    SemverParser.ParseResult pr = SemverParser.parseSemver(version, true, false);
469    if (!pr.isSuccess()) {
470      return false;
471    }
472    return Utilities.isInteger(pr.getMajor()) && isIntegerOrX(pr.getMinor())
473      && (pr.getPatch() == null || isIntegerOrX(pr.getPatch()));
474  }
475
476  private static boolean isIntegerOrX(String p) {
477    return Utilities.existsInList(p, "x", "*", "X") || Utilities.isInteger(p);
478  }
479
480  /**
481   * Returns true if the version string contains any wildcard characters.
482   * Supported wildcards are: * (asterisk) anywhere, x/X (in major/minor/patch only), and ? (question mark suffix).
483   * Note: x and X are only wildcards in version number parts, not in release labels (after -) or build labels (after +).
484   *
485   * @param version version string to check
486   * @return true if version contains any wildcard characters, false otherwise
487   */
488  public static boolean versionHasWildcards(@Nullable String version) {
489    if (Utilities.noString(version)) {
490      return false;
491    }
492
493    // Check for ? suffix wildcard
494    if (version.endsWith("?")) {
495      return true;
496    }
497
498    // Check for * wildcard anywhere
499    if (version.contains("*")) {
500      return true;
501    }
502
503    // For x/X wildcards, we need to check only the version number parts (before any - or +)
504    String versionPart = version;
505    int dashIndex = version.indexOf('-');
506    int plusIndex = version.indexOf('+');
507
508    if (dashIndex >= 0 && plusIndex >= 0) {
509      versionPart = version.substring(0, Math.min(dashIndex, plusIndex));
510    } else if (dashIndex >= 0) {
511      versionPart = version.substring(0, dashIndex);
512    } else if (plusIndex >= 0) {
513      versionPart = version.substring(0, plusIndex);
514    }
515
516    // Check for x/X wildcards only in the version number part
517    return versionPart.contains("x") || versionPart.contains("X");
518  }
519
520  /**
521   * return true if the current version equals criteria, or later, based on the degree of precision specified
522   *
523   * This can be used to check e.g. if a feature is defined in 4.0, if (VersionUtilities.isThisOrLater("4.0", version))
524   *
525   * this is only applicable to valid semver versions (though patch is optional)
526   *
527   * the criteria string can contain wildcards - see @versionMatches
528   *
529   * @param criteria    The value to compare to
530   * @param candidate The value being compared
531   * @param precision how far into the version string to consider (usually just set to full if there's wildcards in the test string)
532   *
533   * @return Is {@literal current} later or equal to {@literal criteria}? For example, if <code>this = 0.5</code> and <code>current = 0.6</code> this method will return true
534   */
535  public static boolean isThisOrLater(@Nonnull String criteria, @Nonnull String candidate, VersionPrecision precision) {
536    criteria = checkVersionNotNullAndValidWildcards(fixForSpecialValue(criteria), "criteria");
537    candidate = checkVersionNotNullAndValid(fixForSpecialValue(candidate), "candidate");
538
539    boolean endsWithQ = false;
540    if (criteria.endsWith("?")) {
541      endsWithQ = true;
542      criteria = criteria.substring(0, criteria.length() - 1);
543    }
544    SemverParser.ParseResult parsedCriteria = SemverParser.parseSemver(criteria, true, false);
545    if (!parsedCriteria.isSuccess()) {
546      throw new FHIRException("Invalid criteria: " + criteria+": ("+parsedCriteria.getError()+")");
547    }
548    SemverParser.ParseResult parsedCandidate = SemverParser.parseSemver(candidate, false, false);
549    if (!parsedCandidate.isSuccess()) {
550      throw new FHIRException("Invalid candidate: " + candidate+" ("+parsedCandidate.getError()+")");
551    }
552    int thisOrLater;
553    thisOrLater = partIsThisOrLater(parsedCriteria.getMajor(), parsedCandidate.getMajor(), true);
554    if (thisOrLater != 0) { return thisOrLater < 0 ?  true : false; }
555    if (endsWithQ && parsedCriteria.getMinor() == null) { return true; }
556    if (precision == VersionPrecision.MAJOR) { return true; }
557    thisOrLater = partIsThisOrLater(parsedCriteria.getMinor(), parsedCandidate.getMinor(), true);
558    if (thisOrLater != 0) { return thisOrLater < 0 ?  true : false; }
559    if (endsWithQ && parsedCriteria.getPatch() == null) { return true; }
560    if (precision == VersionPrecision.MINOR) { return true; }
561    thisOrLater = partIsThisOrLater(parsedCriteria.getPatch(), parsedCandidate.getPatch(), true);
562    if (thisOrLater != 0) { return thisOrLater < 0 ?  true : false; }
563    if (precision == VersionPrecision.PATCH) { return true; }
564    if (endsWithQ && parsedCriteria.getReleaseLabel() == null && parsedCriteria.getBuild() == null) { return true; }
565    thisOrLater = partIsThisOrLater(parsedCriteria.getReleaseLabel(), parsedCandidate.getReleaseLabel(), false);
566    if (thisOrLater != 0) { return thisOrLater < 0 ?  true : false; }
567    thisOrLater = partIsThisOrLater(parsedCriteria.getBuild(), parsedCandidate.getBuild(), false);
568    if (thisOrLater != 0) { return thisOrLater < 0 ?  true : false; }
569    return true;
570  }
571
572
573  private static boolean compareVersionPart(String theTestPart, String theCurrentPart) {
574    if (StringUtils.isNumeric(theTestPart) && StringUtils.isNumeric(theCurrentPart)) {
575      return Integer.parseInt(theCurrentPart) - Integer.parseInt(theTestPart) >= 0;
576    } else {
577      return theCurrentPart.compareTo(theTestPart) >= 0;
578    }
579  }
580
581  private static int compareVersionPartInt(String theTestPart, String theCurrentPart) {
582    if (StringUtils.isNumeric(theTestPart) && StringUtils.isNumeric(theCurrentPart)) {
583      return Integer.parseInt(theCurrentPart) - Integer.parseInt(theTestPart);
584    } else {
585      return theCurrentPart.compareTo(theTestPart);
586    }
587  }
588
589  private static String getLabelPart(String s) {
590    if (Utilities.noString(s)) {
591      return null;
592    }
593    int p = s.indexOf("+");
594    int m = s.indexOf("-");
595    if (p >= 0 && m >= 0) {
596      int e = Integer.min(p, m);
597      return s.substring(e + 1);
598    } else if (p >= 0) {
599      return s.substring(p + 1);
600    } else if (m >= 0) {
601      return s.substring(m + 1);
602    } else {
603      return null;
604    }
605  }
606
607  /**
608   * given any semver, increment the major version and reset the minor and patch to .0.0, and remove any labels
609   */
610  public static String incMajorVersion(String v) {
611    v = removeLabels(checkVersionNotNullAndValid(fixForSpecialValue(v)));
612    int[] parts = splitParts(removeLabels(v));
613    return Integer.toString(parts[0] + 1) + ".0.0";
614  }
615
616  /**
617   * given any semver, increment the minor version and reset the patch to .0 and remove any labels
618   */
619  public static @Nonnull String incMinorVersion(@Nonnull String v) {
620    v = removeLabels(checkVersionNotNullAndValid(fixForSpecialValue(v)));
621    int[] parts = splitParts(removeLabels(v));
622    return Integer.toString(parts[0]) + "." + (parts.length == 1 ? "0.0" : Integer.toString(parts[1] + 1) + ".0");
623  }
624
625  /**
626   * given any semver, increment the patch and remove any labels
627   */
628  public static @Nonnull String incPatchVersion(@Nonnull String v) {
629    v = removeLabels(checkVersionNotNullAndValid(fixForSpecialValue(v)));
630    int[] parts = splitParts(v);
631    return Integer.toString(parts[0]) + "." +
632      (parts.length < 2 ? "0" : Integer.toString(parts[1])) + "." +
633      (parts.length < 3 ? "1" : Integer.toString(parts[2] + 1));
634  }
635
636  private static int[] splitParts(String v) {
637    String[] p = v.split("\\.");
638    return Arrays.stream(p).mapToInt(Integer::parseInt).toArray();
639  }
640
641  /**
642   * Converts version code to standard version string.
643   * @param version version code or string
644   * @return standardized version string
645   */
646  public static String versionFromCode(String version) {
647    return checkVersionNotNullAndValid(fixForSpecialValue(version));
648  }
649
650  /**
651   * Parses version information from a FHIR URL.
652   * @param url FHIR URL to parse
653   * @return VersionURLInfo object or null if not parseable
654   */
655  public static VersionURLInfo parseVersionUrl(String url) {
656    if (url.length() < 24) {
657      return null;
658    }
659    String v = url.substring(20, 24);
660    if (v.endsWith("/")) {
661      v = v.substring(0, v.length() - 1);
662      if (Utilities.existsInList(v, "1.0", "1.4", "3.0", "4.0", "5.0", "6.0")) {
663        return new VersionURLInfo(v, "http://hl7.org/fhir/" + url.substring(24));
664      }
665    }
666    return null;
667  }
668
669
670  /**
671   * same as getCanonicalResourceNames but add R5 supported types that are canonical too
672   */
673  public static Set<String> getExtendedCanonicalResourceNames(String version) {
674    Set<String> res = getCanonicalResourceNames(version);
675    if (isR4Ver(version)) {
676      res.add("ActorDefinition");
677      res.add("Requirements");
678      res.add("SubscriptionTopic");
679      res.add("TestPlan");
680    }
681    return res;
682  }
683
684  /**
685   * Returns set of canonical resource names for the given FHIR version.
686   * @param version FHIR version string
687   * @return set of canonical resource type names
688   */
689  public static Set<String> getCanonicalResourceNames(String version) {
690
691    Set<String> res = new HashSet<String>();
692    if (isR2Ver(version) || isR2BVer(version)) {
693      res.add("ValueSet");
694      res.add("ConceptMap");
695      res.add("NamingSystem");
696      res.add("StructureDefinition");
697      res.add("DataElement");
698      res.add("Conformance");
699      res.add("OperationDefinition");
700      res.add("SearchParameter");
701      res.add("ImplementationGuide");
702      res.add("TestScript");
703    }
704    if (isR3Ver(version)) {
705      res.add("CodeSystem");
706      res.add("CapabilityStatement");
707      res.add("StructureDefinition");
708      res.add("ImplementationGuide");
709      res.add("SearchParameter");
710      res.add("MessageDefinition");
711      res.add("OperationDefinition");
712      res.add("CompartmentDefinition");
713      res.add("StructureMap");
714      res.add("GraphDefinition");
715      res.add("DataElement");
716      res.add("CodeSystem");
717      res.add("ValueSet");
718      res.add("ConceptMap");
719      res.add("ExpansionProfile");
720      res.add("Questionnaire");
721      res.add("ActivityDefinition");
722      res.add("ServiceDefinition");
723      res.add("PlanDefinition");
724      res.add("Measure");
725      res.add("TestScript");
726
727    }
728    if (isR4Ver(version)) {
729      res.add("CodeSystem");
730      res.add("ActivityDefinition");
731      res.add("CapabilityStatement");
732      res.add("ChargeItemDefinition");
733      res.add("CodeSystem");
734      res.add("CompartmentDefinition");
735      res.add("ConceptMap");
736      res.add("EffectEvidenceSynthesis");
737      res.add("EventDefinition");
738      res.add("Evidence");
739      res.add("EvidenceVariable");
740      res.add("ExampleScenario");
741      res.add("GraphDefinition");
742      res.add("ImplementationGuide");
743      res.add("Library");
744      res.add("Measure");
745      res.add("MessageDefinition");
746      res.add("NamingSystem");
747      res.add("OperationDefinition");
748      res.add("PlanDefinition");
749      res.add("Questionnaire");
750      res.add("ResearchDefinition");
751      res.add("ResearchElementDefinition");
752      res.add("RiskEvidenceSynthesis");
753      res.add("SearchParameter");
754      res.add("StructureDefinition");
755      res.add("StructureMap");
756      res.add("TerminologyCapabilities");
757      res.add("TestScript");
758      res.add("ValueSet");
759    }
760    if (isR4BVer(version)) {
761      res.add("ActivityDefinition");
762      res.add("CapabilityStatement");
763      res.add("ChargeItemDefinition");
764      res.add("Citation");
765      res.add("CodeSystem");
766      res.add("CompartmentDefinition");
767      res.add("ConceptMap");
768      res.add("EventDefinition");
769      res.add("Evidence");
770      res.add("EvidenceReport");
771      res.add("EvidenceVariable");
772      res.add("ExampleScenario");
773      res.add("GraphDefinition");
774      res.add("ImplementationGuide");
775      res.add("Library");
776      res.add("Measure");
777      res.add("MessageDefinition");
778      res.add("NamingSystem");
779      res.add("OperationDefinition");
780      res.add("PlanDefinition");
781      res.add("Questionnaire");
782      res.add("ResearchDefinition");
783      res.add("ResearchElementDefinition");
784      res.add("SearchParameter");
785      res.add("SpecimenDefinition");
786      res.add("StructureDefinition");
787      res.add("StructureMap");
788      res.add("SubscriptionTopic");
789      res.add("TerminologyCapabilities");
790      res.add("TestScript");
791      res.add("ValueSet");
792    }
793
794    if (isR5Ver(version) || isR6Ver(version)) {
795      res.add("ActorDefinition");
796      res.add("ActivityDefinition");
797      res.add("CapabilityStatement");
798      res.add("ChargeItemDefinition");
799      res.add("Citation");
800      res.add("ClinicalUseDefinition");
801      res.add("CodeSystem");
802      res.add("CompartmentDefinition");
803      res.add("ConceptMap");
804      res.add("ConditionDefinition");
805      res.add("EventDefinition");
806      res.add("Evidence");
807      res.add("EvidenceReport");
808      res.add("EvidenceVariable");
809      res.add("ExampleScenario");
810      res.add("GraphDefinition");
811      res.add("ImplementationGuide");
812      res.add("Library");
813      res.add("Measure");
814      res.add("MessageDefinition");
815      res.add("NamingSystem");
816      res.add("ObservationDefinition");
817      res.add("OperationDefinition");
818      res.add("PlanDefinition");
819      res.add("Questionnaire");
820      res.add("Requirements");
821      res.add("SearchParameter");
822      res.add("SpecimenDefinition");
823      res.add("StructureDefinition");
824      res.add("StructureMap");
825      res.add("SubscriptionTopic");
826      res.add("TerminologyCapabilities");
827      res.add("TestPlan");
828      res.add("TestScript");
829      res.add("ValueSet");
830    }
831    return res;
832  }
833
834  /**
835   * Extracts FHIR version from package ID.
836   * @param pid package ID string
837   * @return version string or null if not extractable
838   */
839  public static String getVersionForPackage(@Nonnull String pid) {
840    if (pid == null) {
841      return null;
842    }
843    if (pid.startsWith("hl7.fhir.r")) {
844      String[] p = pid.split("\\.");
845      return versionFromCode(p[2]);
846    }
847    return null;
848  }
849
850
851  /**
852   * returns true if v1 and v2 are both semver, and they 'match'
853   *
854   * matching means that the specific version provided in candidate is equal to the value
855   * provided by criteria, or is in the set of values defined by the critteria using
856   * applicable wildcards
857   *
858   * e.g.
859   * 2.0 matches 2.0 and not 2.0.0, 2.0.1 etc
860   * 2.0.0 matches 2.0.0 and not 2.0.1 or 2.0.0-something or 2.0.0+something
861   * 2.* matches 2.0 and 2.1 but not 2.0.0 or 2.1-something
862   * 2.x.x matches 2.0.1 and 2.1.0 etc but not 2.0
863   * 2.0.* matches 2.0.0, 2.0.1, and not 2.0.0-something or 2.0.0+something
864   * 2.0.0-* matches 2.0.0-prerelease or any other label but not 2.0.0+build
865   * 2.0.0+* matches 2.0.0+build or any other build but not 2.0.0 or 2.0.0-prerelease
866   * 2.0.x-* matches 2.0.1-prerelease or 2.0.1-prerelease but not 2.0.0 or 2.0.1
867   * 2.0? matches 2.0, 2.0.1, 2.0.0-build etc - anything that starts with 2.0
868   * 2.0.1? matches 2.0.1, 2.0.1-release, 2.0.1+build etc - anything that starts with 2.0.1
869   * 2.x? matches 2.anything (weird thing to do)
870   *
871   * wildcard summary:
872   *   * = anything that goes in this part. (x and X are also acceptable wildcards for minor and patch, but not for release or build labels, where x and X are valid values)
873   *   ? = anything that goes in this part and ignore the rest of the version. Note that the ? does not follow the part separator.
874   *
875   */
876  public static boolean versionMatches(@Nonnull String criteria, @Nonnull String candidate) {
877    if (Utilities.noString(criteria)) {
878      throw new FHIRException("Invalid criteria: null / empty");
879    }
880    if (Utilities.noString(candidate)) {
881      throw new FHIRException("Invalid candidate: null / empty");
882    }
883    criteria = fixForSpecialValue(criteria);
884    candidate = fixForSpecialValue(candidate);
885
886    boolean endsWithQ = false;
887    if (criteria.endsWith("?")) {
888      endsWithQ = true;
889      criteria = criteria.substring(0, criteria.length() - 1);
890    }
891    SemverParser.ParseResult parsedCriteria = SemverParser.parseSemver(criteria, true, false);
892    if (!parsedCriteria.isSuccess()) {
893      throw new FHIRException("Invalid criteria: " + criteria+": ("+parsedCriteria.getError()+")");
894    }
895    SemverParser.ParseResult parsedCandidate = SemverParser.parseSemver(candidate, false, false);
896    if (!parsedCandidate.isSuccess()) {
897      throw new FHIRException("Invalid candidate: " + candidate+" ("+parsedCandidate.getError()+")");
898    }
899    int pm;
900    if (!partMatches(parsedCriteria.getMajor(), parsedCandidate.getMajor(), true)) { return false; }
901    if (endsWithQ && parsedCriteria.getMinor() == null) { return true; }
902    if (!partMatches(parsedCriteria.getMinor(), parsedCandidate.getMinor(), true)) { return false; }
903    if (endsWithQ && parsedCriteria.getPatch() == null) { return true; }
904    if (!partMatches(parsedCriteria.getPatch(), parsedCandidate.getPatch(), true)) { return false; }
905    if (endsWithQ && parsedCriteria.getReleaseLabel() == null && parsedCriteria.getBuild() == null) { return true; }
906    if (!partMatches(parsedCriteria.getReleaseLabel(), parsedCandidate.getReleaseLabel(), false)) { return false; }
907    if (!partMatches(parsedCriteria.getBuild(), parsedCandidate.getBuild(), false)) { return false; }
908    return true;
909  }
910
911  private static boolean partMatches(String criteria, String candidate, boolean allowX) {
912    if (criteria == null) {
913      return candidate == null;
914    } else {
915      if (allowX ? Utilities.existsInList(criteria, "*", "x", "X") : Utilities.existsInList(criteria, "*")) {
916        return candidate != null;
917      } else {
918        return criteria.equals(candidate);
919      }
920    }
921  }
922
923  private static int partIsThisOrLater(String criteria, String candidate, boolean allowX) {
924    if (criteria == null) {
925      if (candidate == null) {
926        return 0;
927      } else {
928        return allowX ? -1 : 1;
929      }
930    } else if (candidate == null) {
931      return allowX ? 1 : -1;
932    } else if (allowX ? Utilities.existsInList(criteria, "*", "x", "X") : Utilities.existsInList(criteria, "*")) {
933      return -1;
934    } else if (Utilities.isInteger(criteria) && Utilities.isInteger(candidate)) {
935      return Integer.parseInt(criteria) - Integer.parseInt(candidate);
936    } else {
937      return criteria.compareTo(candidate);
938    }
939  }
940
941
942  /**
943   * returns true if v1 matches any v2 using the rules for @versionMatches()
944   */
945  public static boolean versionMatchesList(@Nonnull String v1, @Nonnull List<String> v2l) {
946    for (String v2 : v2l) {
947      if (versionMatches(v1, v2)) {
948        return true;
949      }
950    }
951    return false;
952  }
953
954  /**
955   * Given a canonical URL of format {url}|{version}, remove the version part
956   */
957  public static @Nullable String removeVersionFromCanonical(@Nullable String url) {
958    if (url == null) {
959      return null;
960    }
961    if (url.contains("|")) {
962      return url.substring(0, url.indexOf("|"));
963    } else {
964      return url;
965    }
966  }
967
968  /**
969   * Returns the specification URL for the given FHIR version.
970   * @param v FHIR version string
971   * @return specification URL
972   */
973  public static String getSpecUrl(@Nonnull String v) {
974    v = removeLabels(checkVersionNotNullAndValidWildcards(fixForSpecialValue(v)));
975    switch (getMajMinPriv(v)) {
976      case "0.0":
977        return "http://hl7.org/fhir/DSTU1";
978      case "1.0":
979        return "http://hl7.org/fhir/DSTU2";
980      case "1.4":
981        return "http://hl7.org/fhir/2016May";
982      case "3.0":
983        return "http://hl7.org/fhir/STU3";
984      case "4.0":
985        return "http://hl7.org/fhir/R4";
986      case "4.3":
987        return "http://hl7.org/fhir/R4B";
988      case "5.0":
989        return "http://hl7.org/fhir/R5";
990      case "6.0":
991        return "http://build.fhir.org";
992      default:
993        return "http://hl7.org/fhir";
994    }
995  }
996
997  /**
998   * Returns the release name (R2, R3, etc.) for the given version.
999   * @param v FHIR version string
1000   * @return release name (e.g., "R4", "R5")
1001   */
1002  public static @Nonnull String getNameForVersion(@Nonnull String v) {
1003    v = removeLabels(checkVersionNotNullAndValidWildcards(fixForSpecialValue(v)));
1004    switch (getMajMinPriv(v)) {
1005      case "1.0":
1006        return "R2";
1007      case "1.4":
1008        return "R2B";
1009      case "3.0":
1010        return "R3";
1011      case "4.0":
1012        return "R4";
1013      case "4.3":
1014        return "R4B";
1015      case "5.0":
1016        return "R5";
1017      case "6.0":
1018        return "R6";
1019      default:
1020        return "R?";
1021    }
1022  }
1023
1024  /**
1025   * given version ver1 and ver2, compare them as semver strings (special values also accepted).
1026   * -1 means ver1 is earlier, 0 means they 'match' and 1 means ver2 is later (normal java sort order)
1027   */
1028  public static int compareVersions(@Nullable String ver1, @Nullable String ver2) {
1029    ver1 = checkVersionValid(fixForSpecialValue(ver1), "ver1");
1030    ver2 = checkVersionValid(fixForSpecialValue(ver2), "ver2");
1031
1032    if (ver1 != null && ver2 != null) {
1033      SemverParser.ParseResult pr1 = SemverParser.parseSemver(ver1, false, false);
1034      SemverParser.ParseResult pr2 = SemverParser.parseSemver(ver2, false, false);
1035      int res = compareVersionStrings(pr1.getMajor(), pr2.getMajor(), true, false);
1036      if (res == 0) {
1037        res = compareVersionStrings(pr1.getMinor(), pr2.getMinor(), true, false);
1038      }
1039      if (res == 0) {
1040        res = compareVersionStrings(pr1.getPatch(), pr2.getPatch(), true, false);
1041      }
1042      if (res == 0) {
1043        res = compareVersionStrings(pr1.getReleaseLabel(), pr2.getReleaseLabel(), false, true);
1044      }
1045      if (res == 0) {
1046        res = compareVersionStrings(pr1.getBuild(), pr2.getBuild(), false, true);
1047      }
1048      return res;
1049    } else if (ver1 == null) {
1050      return ver2 == null ? 0 : -1;
1051    } else { // if (ver2 == null) {
1052      return 1;
1053    }
1054  }
1055
1056  private static int compareVersionStrings(String v1, String v2, boolean asInteger, boolean inverted) {
1057    if (v1 == null) {
1058      if (v2 == null) {
1059        return 0;
1060      } else {
1061        return inverted ? 1 : -1;
1062      }
1063    } else if (v2 == null) {
1064      return inverted ? -1 : 1;
1065    } else if (asInteger || Utilities.isInteger(v2) && !Utilities.isInteger(v1)) {
1066      int r = Integer.compare(Integer.parseInt(v1), Integer.parseInt(v2));
1067      if (r == 0) {
1068        return 0;
1069      } else if (r < 0) {
1070        return -1;
1071      } else {
1072        return 1;
1073      }
1074    } else {
1075      int r = v1.compareTo(v2);
1076      if (r == 0) {
1077        return 0;
1078      } else if (r < 0) {
1079        return -1;
1080      } else {
1081        return 1;
1082      }
1083    }
1084  }
1085
1086  /**
1087   * true of ver is included in the range bounded by startVer and stopVer (or matches - bounds and inclusive)
1088   * <p>
1089   * Special values also accepted e.g. r3 is in r3 to r5
1090   *
1091   * @param ver
1092   * @return
1093   */
1094  public static boolean includedInRange(@Nonnull String startVer, @Nonnull String stopVer, @Nonnull String ver) {
1095    startVer = removeLabels(checkVersionNotNullAndValid(fixForSpecialValue(startVer), "startVer"));
1096    stopVer = removeLabels(checkVersionNotNullAndValid(fixForSpecialValue(stopVer), "stopVer"));
1097    ver = removeLabels(checkVersionNotNullAndValid(fixForSpecialValue(ver), "ver"));
1098
1099    if (ver.equals(startVer)) {
1100      return true;
1101    }
1102    if (ver.equals(stopVer)) {
1103      return true;
1104    }
1105    return startVer.compareTo(ver) < 0 && stopVer.compareTo(ver) > 0;
1106  }
1107
1108  /**
1109   * Returns the resource types URL for the given FHIR version.
1110   * @param version FHIR version string
1111   * @return resource types URL
1112   */
1113  public static String getResourceTypesUrl(@Nonnull String version) {
1114    if (isR5Plus(version)) {
1115      return "http://hl7.org/fhir/fhir-types";
1116    } else {
1117      return "http://hl7.org/fhir/resource-types";
1118    }
1119  }
1120
1121  /**
1122   * given a range of core versions, list all the ones in the range (accepts either version of special values, returns actual versions)
1123   */
1124  public static List<String> iterateCorePublishedVersions(@Nonnull String startVer, @Nonnull String stopVer) {
1125    startVer = removeLabels(checkVersionNotNullAndValid(fixForSpecialValue(startVer), "startVer"));
1126    stopVer = removeLabels(checkVersionNotNullAndValid(fixForSpecialValue(stopVer), "stopVer"));
1127    List<String> result = new ArrayList<>();
1128    if (isThisOrLater(startVer, "1.0", VersionPrecision.MINOR) && isThisOrLater("1.0", stopVer, VersionPrecision.MINOR)) {
1129      result.add("1.0");
1130    }
1131    if (isThisOrLater(startVer, "3.0", VersionPrecision.MINOR) && isThisOrLater("3.0", stopVer, VersionPrecision.MINOR)) {
1132      result.add("3.0");
1133    }
1134    if (isThisOrLater(startVer, "4.0", VersionPrecision.MINOR) && isThisOrLater("4.0", stopVer, VersionPrecision.MINOR)) {
1135      result.add("4.0");
1136    }
1137    if (isThisOrLater(startVer, "4.3", VersionPrecision.MINOR) && isThisOrLater("4.3", stopVer, VersionPrecision.MINOR)) {
1138      result.add("4.3");
1139    }
1140    if (isThisOrLater(startVer, "5.0", VersionPrecision.MINOR) && isThisOrLater("5.0", stopVer, VersionPrecision.MINOR)) {
1141      result.add("5.0");
1142    }
1143    return result;
1144  }
1145
1146
1147  private static String removeLabels(String version) {
1148    if (Utilities.noString(version))
1149      return null;
1150    if (version.contains("+")) {
1151      version = version.substring(0, version.indexOf("+"));
1152    }
1153    if (version.contains("-")) {
1154      version = version.substring(0, version.indexOf("-"));
1155    }
1156    return version;
1157  }
1158
1159
1160  private static String checkVersionNotNullAndValid(String s) {
1161    if (s == null) {
1162      throw new FHIRException("Invalid version: null");
1163    } else if (!isSemVer(s)) {
1164      throw new FHIRException("Invalid version: '" + s + '"');
1165    } else {
1166      return s;
1167    }
1168  }
1169
1170  public static String checkVersionNotNullAndValid(String s, String label) {
1171    if (s == null) {
1172      throw new FHIRException("Invalid " + label + " version: null");
1173    } else if (!isSemVer(s)) {
1174      throw new FHIRException("Invalid " + label + " version: '" + s + "'");
1175    } else {
1176      return s;
1177    }
1178  }
1179
1180  private static String checkVersionNotNullAndValidWildcards(String s) {
1181    if (s == null) {
1182      throw new FHIRException("Invalid version: null");
1183    } else if (!isSemVerWithWildcards(s)) {
1184      throw new FHIRException("Invalid version: '" + s + '"');
1185    } else {
1186      return s;
1187    }
1188  }
1189
1190  private static String checkVersionNotNullAndValidWildcards(String s, String label) {
1191    if (s == null) {
1192      throw new FHIRException("Invalid " + label + " version: null");
1193    } else if (!isSemVerWithWildcards(s)) {
1194      throw new FHIRException("Invalid " + label + " version: '" + s + '"');
1195    } else {
1196      return s;
1197    }
1198  }
1199
1200
1201  private static String checkVersionValid(String s) {
1202    if (s == null) {
1203      return null;
1204    } else if (!isSemVer(s)) {
1205      throw new FHIRException("Invalid version: '" + s + '"');
1206    } else {
1207      return s;
1208    }
1209  }
1210
1211  private static String checkVersionValidWildcards(String s) {
1212    if (s == null) {
1213      return null;
1214    } else if (!isSemVerWithWildcards(s)) {
1215      throw new FHIRException("Invalid version: '" + s + '"');
1216    } else {
1217      return s;
1218    }
1219  }
1220
1221  private static String checkVersionValid(String s, String label) {
1222    if (s == null) {
1223      return null;
1224    } else if (!isSemVer(s)) {
1225      throw new FHIRException("Invalid " + label + " version: '" + s + '"');
1226    } else {
1227      return s;
1228    }
1229  }
1230
1231  private static String checkVersionNotNull(String s) {
1232    if (s == null) {
1233      throw new FHIRException("Invalid version: null");
1234    } else {
1235      return s;
1236    }
1237  }
1238
1239  private static String checkVersionNotNull(String s, String label) {
1240    if (s == null) {
1241      throw new FHIRException("Invalid " + label + " version: null");
1242    } else {
1243      return s;
1244    }
1245  }
1246
1247  public static String fixForSpecialValue(String version) {
1248    if (Utilities.noString(version)) {
1249      return null;
1250    }
1251    if (version.startsWith("http://hl7.org/fhir/")) {
1252      version = version.substring(20);
1253      if (version.contains("/")) {
1254        version = version.substring(0, version.indexOf("/"));
1255      }
1256    }
1257
1258    switch (version.toUpperCase()) {
1259      case "R2":
1260        return "1.0.2";
1261      case "DSTU2":
1262        return "1.0.2";
1263      case "R2B":
1264        return "1.4.0";
1265      case "R3":
1266        return "3.0.2";
1267      case "STU3":
1268        return "3.0.2";
1269      case "R4":
1270        return "4.0.1";
1271      case "R4B":
1272        return "4.3.0";
1273      case "R5":
1274        return "5.0.0";
1275      case "R6":
1276        return "6.0.0-cibuild";
1277      default:
1278        return version;
1279    }
1280  }
1281
1282}