001/*
002 * SPDX-FileCopyrightText: none
003 * SPDX-License-Identifier: CC0-1.0
004 */
005
006package dev.metaschema.oscal.lib.profile.resolver.policy;
007
008import dev.metaschema.oscal.lib.profile.resolver.ProfileResolutionEvaluationException;
009import edu.umd.cs.findbugs.annotations.NonNull;
010import edu.umd.cs.findbugs.annotations.Nullable;
011
012public interface IIdentifierParser {
013  @NonNull
014  IIdentifierParser FRAGMENT_PARSER = new PatternIdentifierParser("^#([^#]+)(?:#.*)?$", 1);
015  @NonNull
016  IIdentifierParser IDENTITY_PARSER = new IIdentifierParser() {
017
018    @Override
019    public String parse(@NonNull String reference) {
020      return reference;
021    }
022
023    @Override
024    public String update(@NonNull String reference, @NonNull String newIdentifier) {
025      return newIdentifier;
026    }
027  };
028
029  /**
030   * Parse the {@code referenceText} for the identifier.
031   *
032   * @param referenceText
033   *          the reference text containing the identifier
034   * @return the identifier, or {@code null} if the identifier could not be parsed
035   */
036  @Nullable
037  String parse(@NonNull String referenceText);
038
039  /**
040   * Substitute the provided {@code newIdentifier} with the identifier in the
041   * {@code referenceText}.
042   *
043   * @param referenceText
044   *          the reference text containing the original identifier
045   * @param newIdentifier
046   *          the new identifier to replace the existing identifier
047   * @return the updated reference text with the identifier replaced
048   * @throws ProfileResolutionEvaluationException
049   *           if the identifier could not be updated
050   */
051  @NonNull
052  String update(@NonNull String referenceText, @NonNull String newIdentifier);
053}