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}