// Generated from: ../../../../../../../../oscal/src/metaschema/oscal_mapping-common_metaschema.xml
// Do not edit - changes will be lost when regenerated.
package dev.metaschema.oscal.lib.model;

import dev.metaschema.core.datatype.adapter.StringAdapter;
import dev.metaschema.core.datatype.adapter.TokenAdapter;
import dev.metaschema.core.datatype.adapter.UriAdapter;
import dev.metaschema.core.datatype.adapter.UuidAdapter;
import dev.metaschema.core.datatype.markup.MarkupMultiline;
import dev.metaschema.core.datatype.markup.MarkupMultilineAdapter;
import dev.metaschema.core.model.IBoundObject;
import dev.metaschema.core.model.IMetaschemaData;
import dev.metaschema.core.model.JsonGroupAsBehavior;
import dev.metaschema.core.model.constraint.IConstraint;
import dev.metaschema.core.util.ObjectUtils;
import dev.metaschema.databind.model.annotations.AllowedValue;
import dev.metaschema.databind.model.annotations.AllowedValues;
import dev.metaschema.databind.model.annotations.BoundAssembly;
import dev.metaschema.databind.model.annotations.BoundField;
import dev.metaschema.databind.model.annotations.BoundFlag;
import dev.metaschema.databind.model.annotations.GroupAs;
import dev.metaschema.databind.model.annotations.MetaschemaAssembly;
import dev.metaschema.databind.model.annotations.ValueConstraints;
import edu.umd.cs.findbugs.annotations.NonNull;
import edu.umd.cs.findbugs.annotations.Nullable;
import java.net.URI;
import java.util.LinkedList;
import java.util.List;
import java.util.UUID;
import org.apache.commons.lang3.builder.ReflectionToStringBuilder;
import org.apache.commons.lang3.builder.ToStringStyle;

/**
 * A relationship-based mapping between a source and target set consisting of members (i.e., controls, control statements) from the respective source and target.
 */
@MetaschemaAssembly(
    formalName = "Mapping Entry",
    description = "A relationship-based mapping between a source and target set consisting of members (i.e., controls, control statements) from the respective source and target.",
    name = "map",
    moduleClass = OscalMappingCommonModule.class
)
public class MappingEntry implements IBoundObject {
  private final IMetaschemaData __metaschemaData;

  /**
   * The unique identifier for the mapping entry.
   */
  @BoundFlag(
      formalName = "Mapping Entry Identifier",
      description = "The unique identifier for the mapping entry.",
      name = "uuid",
      required = true,
      typeAdapter = UuidAdapter.class
  )
  private UUID _uuid;

  /**
   * A namespace qualifying the relationship's value. This allows different organizations to associate distinct semantics for relationships with the same name.
   */
  @BoundFlag(
      formalName = "Relationship Value Namespace",
      description = "A namespace qualifying the relationship's value. This allows different organizations to associate distinct semantics for relationships with the same name.",
      name = "ns",
      defaultValue = "http://csrc.nist.gov/ns/oscal",
      typeAdapter = UriAdapter.class,
      remarks = "This value must be an [absolute URI](https://pages.nist.gov/OSCAL/concepts/uri-use/#absolute-uri) that serves as a [naming system identifier](https://pages.nist.gov/OSCAL/concepts/uri-use/#use-as-a-naming-system-identifier).\n"
              + "\n"
              + "When a `ns` is not provided, its value should be assumed to be ` http://csrc.nist.gov/ns/oscal` and the name should be a name defined by the associated OSCAL model."
  )
  private URI _ns;

  /**
   * The method used for relating controls within the mapping. The supported methods are aligned with the <a href="https://doi.org/10.6028/NIST.IR.8477">NIST Interagency Report (IR) 8477</a>, Section 4.3 Set Theory Relationship Mapping.
   */
  @BoundFlag(
      formalName = "Matching",
      description = "The method used for relating controls within the mapping. The supported methods are aligned with the [NIST Interagency Report (IR) 8477](https://doi.org/10.6028/NIST.IR.8477), Section 4.3 Set Theory Relationship Mapping.",
      name = "matching-rationale",
      typeAdapter = StringAdapter.class,
      valueConstraints = @ValueConstraints(allowedValues = @AllowedValues(level = IConstraint.Level.ERROR, values = {@AllowedValue(value = "syntactic", description = "Syntactic: How similar is the *wording* that expresses the two concepts. This is a word-for-word analysis of the relationship, not an interpretation of the language."), @AllowedValue(value = "semantic", description = "Semantic: How similar are the *meanings* of the two concepts? This involves some interpretation of each concept’s language."), @AllowedValue(value = "functional", description = "Functional: How similar are the *results* of executing the two concepts? This involves understanding what will happen if the two concepts are implemented, performed, or otherwise executed.")}))
  )
  private String _matchingRationale;

  /**
   * The relationship type for the mapping entry, which describes the relationship between the effective requirements of the specified source and target sets in the context of the <code>matching-rationale</code> method globaly defined in the <code>provenance</code> unless overwritten locally in the <code> map</code>. The <code>relationship</code> type and the <code>matching-rationale</code> must be used together. However, more than one <code>matching-rationale</code> method may apply to a <code>source</code> and <code>target</code> pair.
   */
  @BoundField(
      formalName = "Mapping Entry Relationship",
      description = "The relationship type for the mapping entry, which describes the relationship between the effective requirements of the specified source and target sets in the context of the `matching-rationale` method globaly defined in the `provenance` unless overwritten locally in the ` map`. The `relationship` type and the `matching-rationale` must be used together. However, more than one `matching-rationale` method may apply to a `source` and `target` pair.",
      useName = "relationship",
      remarks = "For example, consider the CSF 1.1's PR.AC-1, \"Identities and credentials are issued, managed, verified, revoked, and audited for authorized devices, users and processes\", and the Privacy Framework's PR.AC-P1, \"Identities and credentials are issued, managed, verified, and devices.\"\n"
              + "\n"
              + "These two requirements have identical wording except for \"users\" versus \"individuals\" and the order of the last few words. With a \\`matching-rationale\\` of syntactic, the relationship type would beintersects with because the two overlap, but each includes content that the other does not. However, with a rationale of semantic, the relationship type would be equal if \"users\" and \"individuals\" have the same meaning in their respective sources, subset if \"users\" was a subset of \"individuals,\" and so on.\n"
              + "\n"
              + "When establishing relationships, mapping SHOULD be done at the control statement level where possible. This approach allows for a more accurate relationship.",
      minOccurs = 1,
      typeAdapter = TokenAdapter.class,
      valueConstraints = @ValueConstraints(allowedValues = @AllowedValues(level = IConstraint.Level.ERROR, target = ".[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]", values = {@AllowedValue(value = "equivalent-to", description = "The `source` and `target` requirements are similar, although not necessarily identical. The words may differ, but both mapped sets convey similar information with the same effective meaning. This relationship may be reversed, since \\`A equivalent-to B\\` also means that \\`B equivalent-to A\\`. This relationship is less suitable for a *syntactic* `matching-rationale` ."), @AllowedValue(value = "equal-to", description = "The `source` and `target` requirements are the same. Differences in capitalization, spelling, and grammar can be ignored, if these differences do not change the meaning. This relationship may be reversed, since \\`A equal-to B\\` also means that \\`B equal-to A\\`."), @AllowedValue(value = "subset-of", description = "The `source` requirements are a subset of ` target` requirements. In other words, `target` contains all `source`requirements and aditional others. This relationship may be reversed as a \\`superset-of\\`, since \\`A subset-of B\\` also means that \\`B superset-of A\\`."), @AllowedValue(value = "superset-of", description = "The `source` requirements are a superset of `target` requirements. In other words, ` source` contains all `target`requirements and aditional others. This relationship may be reversed as a \\`subset-of\\`, since \\`A superset-of B\\` also means that \\`B subset-of A\\`."), @AllowedValue(value = "intersects-with", description = "The `source` and `target` requirements have some overlap, but each includes content that the other does not. This relationship may be reversed, since \\`A intersects-with B\\` also means that \\`B intersects-with A\\`. A mapping at statement level could result on `relationships` mapping that allows for more inference than using this relationship type."), @AllowedValue(value = "no-relationship", description = "The `source` and `target` requirements are not related; their content does not overlap. This relation is introduced not with the intention to support exhaustiv mapping of all requirements and statements that have no overlap, but rather to support edge cases such is the need to tailor a ` relationship` in the context of a component or system to better align with the implementation and configuration of the respective component or system. Also, this `relationship` is provided in support of the [NIST IR 8477](https://doi.org/10.6028/NIST.IR.8477).")}))
  )
  private String _relationship;

  /**
   * A specific edge within a source or target that is the subject of a mapping.
   */
  @BoundAssembly(
      formalName = "Mapping Entry Item (source or target)",
      description = "A specific edge within a source or target that is the subject of a mapping.",
      useName = "source",
      minOccurs = 1,
      maxOccurs = -1,
      groupAs = @GroupAs(name = "sources", inJson = JsonGroupAsBehavior.LIST)
  )
  private List<MappingItem> _sources;

  /**
   * A specific edge within a source or target that is the subject of a mapping.
   */
  @BoundAssembly(
      formalName = "Mapping Entry Item (source or target)",
      description = "A specific edge within a source or target that is the subject of a mapping.",
      useName = "target",
      minOccurs = 1,
      maxOccurs = -1,
      groupAs = @GroupAs(name = "targets", inJson = JsonGroupAsBehavior.LIST)
  )
  private List<MappingItem> _targets;

  /**
   * Describes requirements, incompatibilities and gaps that are identified between a target and source in a mapping item.
   */
  @BoundAssembly(
      formalName = "Relationship Qualifier",
      description = "Describes requirements, incompatibilities and gaps that are identified between a target and source in a mapping item.",
      useName = "qualifier",
      maxOccurs = -1,
      groupAs = @GroupAs(name = "qualifiers", inJson = JsonGroupAsBehavior.LIST)
  )
  private List<QualifierItem> _qualifiers;

  /**
   * This records either a string category or a decimal value from 0-1 representing a percentage. Both of these values describe an estimation of the author's confidence that this mapping is correct and accurate.
   */
  @BoundField(
      formalName = "Confidence Score",
      description = "This records either a string category or a decimal value from 0-1 representing a percentage. Both of these values describe an estimation of the author's confidence that this mapping is correct and accurate.",
      useName = "confidence-score"
  )
  private ConfidenceScore _confidenceScore;

  /**
   * A decimal value from 0-1, representing the percentage coverage of the targets by the sources.
   */
  @BoundField(
      formalName = "Coverage",
      description = "A decimal value from 0-1, representing the percentage coverage of the targets by the sources.",
      useName = "coverage"
  )
  private Coverage _coverage;

  /**
   * An attribute, characteristic, or quality of the containing object expressed as a namespace qualified name/value pair.
   */
  @BoundAssembly(
      formalName = "Property",
      description = "An attribute, characteristic, or quality of the containing object expressed as a namespace qualified name/value pair.",
      useName = "prop",
      maxOccurs = -1,
      groupAs = @GroupAs(name = "props", inJson = JsonGroupAsBehavior.LIST)
  )
  private List<Property> _props;

  /**
   * A reference to a local or remote resource, that has a specific relation to the containing object.
   */
  @BoundAssembly(
      formalName = "Link",
      description = "A reference to a local or remote resource, that has a specific relation to the containing object.",
      useName = "link",
      maxOccurs = -1,
      groupAs = @GroupAs(name = "links", inJson = JsonGroupAsBehavior.LIST)
  )
  private List<Link> _links;

  /**
   * Additional commentary about the containing object.
   */
  @BoundField(
      formalName = "Remarks",
      description = "Additional commentary about the containing object.",
      useName = "remarks",
      typeAdapter = MarkupMultilineAdapter.class
  )
  private MarkupMultiline _remarks;

  /**
   * Constructs a new {@code dev.metaschema.oscal.lib.model.MappingEntry} instance with no metadata.
   */
  public MappingEntry() {
    this(null);
  }

  /**
   * Constructs a new {@code dev.metaschema.oscal.lib.model.MappingEntry} instance with the specified metadata.
   *
   * @param data
   *           the metaschema data, or {@code null} if none
   */
  public MappingEntry(IMetaschemaData data) {
    this.__metaschemaData = data;
  }

  @Override
  public IMetaschemaData getMetaschemaData() {
    return __metaschemaData;
  }

  /**
   * Get the "{@literal Mapping Entry Identifier}".
   *
   * <p>
   * The unique identifier for the mapping entry.
   *
   * @return the uuid value
   */
  @NonNull
  public UUID getUuid() {
    return _uuid;
  }

  /**
   * Set the "{@literal Mapping Entry Identifier}".
   *
   * <p>
   * The unique identifier for the mapping entry.
   *
   * @param value
   *           the uuid value to set
   */
  public void setUuid(@NonNull UUID value) {
    _uuid = value;
  }

  /**
   * Get the "{@literal Relationship Value Namespace}".
   *
   * <p>
   * A namespace qualifying the relationship's value. This allows different organizations to associate distinct semantics for relationships with the same name.
   *
   * @return the ns value, or {@code null} if not set
   */
  @Nullable
  public URI getNs() {
    return _ns;
  }

  /**
   * Set the "{@literal Relationship Value Namespace}".
   *
   * <p>
   * A namespace qualifying the relationship's value. This allows different organizations to associate distinct semantics for relationships with the same name.
   *
   * @param value
   *           the ns value to set, or {@code null} to clear
   */
  public void setNs(@Nullable URI value) {
    _ns = value;
  }

  /**
   * Get the "{@literal Matching}".
   *
   * <p>
   * The method used for relating controls within the mapping. The supported methods are aligned with the <a href="https://doi.org/10.6028/NIST.IR.8477">NIST Interagency Report (IR) 8477</a>, Section 4.3 Set Theory Relationship Mapping.
   *
   * @return the matching-rationale value, or {@code null} if not set
   */
  @Nullable
  public String getMatchingRationale() {
    return _matchingRationale;
  }

  /**
   * Set the "{@literal Matching}".
   *
   * <p>
   * The method used for relating controls within the mapping. The supported methods are aligned with the <a href="https://doi.org/10.6028/NIST.IR.8477">NIST Interagency Report (IR) 8477</a>, Section 4.3 Set Theory Relationship Mapping.
   *
   * @param value
   *           the matching-rationale value to set, or {@code null} to clear
   */
  public void setMatchingRationale(@Nullable String value) {
    _matchingRationale = value;
  }

  /**
   * Get the "{@literal Mapping Entry Relationship}".
   *
   * <p>
   * The relationship type for the mapping entry, which describes the relationship between the effective requirements of the specified source and target sets in the context of the <code>matching-rationale</code> method globaly defined in the <code>provenance</code> unless overwritten locally in the <code> map</code>. The <code>relationship</code> type and the <code>matching-rationale</code> must be used together. However, more than one <code>matching-rationale</code> method may apply to a <code>source</code> and <code>target</code> pair.
   *
   * @return the relationship value
   */
  @NonNull
  public String getRelationship() {
    return _relationship;
  }

  /**
   * Set the "{@literal Mapping Entry Relationship}".
   *
   * <p>
   * The relationship type for the mapping entry, which describes the relationship between the effective requirements of the specified source and target sets in the context of the <code>matching-rationale</code> method globaly defined in the <code>provenance</code> unless overwritten locally in the <code> map</code>. The <code>relationship</code> type and the <code>matching-rationale</code> must be used together. However, more than one <code>matching-rationale</code> method may apply to a <code>source</code> and <code>target</code> pair.
   *
   * @param value
   *           the relationship value to set
   */
  public void setRelationship(@NonNull String value) {
    _relationship = value;
  }

  /**
   * Get the "{@literal Mapping Entry Item (source or target)}".
   *
   * <p>
   * A specific edge within a source or target that is the subject of a mapping.
   *
   * @return the source value
   */
  @NonNull
  public List<MappingItem> getSources() {
    if (_sources == null) {
      _sources = new LinkedList<>();
    }
    return ObjectUtils.notNull(_sources);
  }

  /**
   * Set the "{@literal Mapping Entry Item (source or target)}".
   *
   * <p>
   * A specific edge within a source or target that is the subject of a mapping.
   *
   * @param value
   *           the source value to set
   */
  public void setSources(@NonNull List<MappingItem> value) {
    _sources = value;
  }

  /**
   * Add a new {@link MappingItem} item to the underlying collection.
   * @param item the item to add
   * @return {@code true}
   */
  public boolean addSource(MappingItem item) {
    MappingItem value = ObjectUtils.requireNonNull(item,"item cannot be null");
    if (_sources == null) {
      _sources = new LinkedList<>();
    }
    return _sources.add(value);
  }

  /**
   * Remove the first matching {@link MappingItem} item from the underlying collection.
   * @param item the item to remove
   * @return {@code true} if the item was removed or {@code false} otherwise
   */
  public boolean removeSource(MappingItem item) {
    MappingItem value = ObjectUtils.requireNonNull(item,"item cannot be null");
    return _sources != null && _sources.remove(value);
  }

  /**
   * Get the "{@literal Mapping Entry Item (source or target)}".
   *
   * <p>
   * A specific edge within a source or target that is the subject of a mapping.
   *
   * @return the target value
   */
  @NonNull
  public List<MappingItem> getTargets() {
    if (_targets == null) {
      _targets = new LinkedList<>();
    }
    return ObjectUtils.notNull(_targets);
  }

  /**
   * Set the "{@literal Mapping Entry Item (source or target)}".
   *
   * <p>
   * A specific edge within a source or target that is the subject of a mapping.
   *
   * @param value
   *           the target value to set
   */
  public void setTargets(@NonNull List<MappingItem> value) {
    _targets = value;
  }

  /**
   * Add a new {@link MappingItem} item to the underlying collection.
   * @param item the item to add
   * @return {@code true}
   */
  public boolean addTarget(MappingItem item) {
    MappingItem value = ObjectUtils.requireNonNull(item,"item cannot be null");
    if (_targets == null) {
      _targets = new LinkedList<>();
    }
    return _targets.add(value);
  }

  /**
   * Remove the first matching {@link MappingItem} item from the underlying collection.
   * @param item the item to remove
   * @return {@code true} if the item was removed or {@code false} otherwise
   */
  public boolean removeTarget(MappingItem item) {
    MappingItem value = ObjectUtils.requireNonNull(item,"item cannot be null");
    return _targets != null && _targets.remove(value);
  }

  /**
   * Get the "{@literal Relationship Qualifier}".
   *
   * <p>
   * Describes requirements, incompatibilities and gaps that are identified between a target and source in a mapping item.
   *
   * @return the qualifier value
   */
  @NonNull
  public List<QualifierItem> getQualifiers() {
    if (_qualifiers == null) {
      _qualifiers = new LinkedList<>();
    }
    return ObjectUtils.notNull(_qualifiers);
  }

  /**
   * Set the "{@literal Relationship Qualifier}".
   *
   * <p>
   * Describes requirements, incompatibilities and gaps that are identified between a target and source in a mapping item.
   *
   * @param value
   *           the qualifier value to set
   */
  public void setQualifiers(@NonNull List<QualifierItem> value) {
    _qualifiers = value;
  }

  /**
   * Add a new {@link QualifierItem} item to the underlying collection.
   * @param item the item to add
   * @return {@code true}
   */
  public boolean addQualifier(QualifierItem item) {
    QualifierItem value = ObjectUtils.requireNonNull(item,"item cannot be null");
    if (_qualifiers == null) {
      _qualifiers = new LinkedList<>();
    }
    return _qualifiers.add(value);
  }

  /**
   * Remove the first matching {@link QualifierItem} item from the underlying collection.
   * @param item the item to remove
   * @return {@code true} if the item was removed or {@code false} otherwise
   */
  public boolean removeQualifier(QualifierItem item) {
    QualifierItem value = ObjectUtils.requireNonNull(item,"item cannot be null");
    return _qualifiers != null && _qualifiers.remove(value);
  }

  /**
   * Get the "{@literal Confidence Score}".
   *
   * <p>
   * This records either a string category or a decimal value from 0-1 representing a percentage. Both of these values describe an estimation of the author's confidence that this mapping is correct and accurate.
   *
   * @return the confidence-score value, or {@code null} if not set
   */
  @Nullable
  public ConfidenceScore getConfidenceScore() {
    return _confidenceScore;
  }

  /**
   * Set the "{@literal Confidence Score}".
   *
   * <p>
   * This records either a string category or a decimal value from 0-1 representing a percentage. Both of these values describe an estimation of the author's confidence that this mapping is correct and accurate.
   *
   * @param value
   *           the confidence-score value to set, or {@code null} to clear
   */
  public void setConfidenceScore(@Nullable ConfidenceScore value) {
    _confidenceScore = value;
  }

  /**
   * Get the "{@literal Coverage}".
   *
   * <p>
   * A decimal value from 0-1, representing the percentage coverage of the targets by the sources.
   *
   * @return the coverage value, or {@code null} if not set
   */
  @Nullable
  public Coverage getCoverage() {
    return _coverage;
  }

  /**
   * Set the "{@literal Coverage}".
   *
   * <p>
   * A decimal value from 0-1, representing the percentage coverage of the targets by the sources.
   *
   * @param value
   *           the coverage value to set, or {@code null} to clear
   */
  public void setCoverage(@Nullable Coverage value) {
    _coverage = value;
  }

  /**
   * Get the "{@literal Property}".
   *
   * <p>
   * An attribute, characteristic, or quality of the containing object expressed as a namespace qualified name/value pair.
   *
   * @return the prop value
   */
  @NonNull
  public List<Property> getProps() {
    if (_props == null) {
      _props = new LinkedList<>();
    }
    return ObjectUtils.notNull(_props);
  }

  /**
   * Set the "{@literal Property}".
   *
   * <p>
   * An attribute, characteristic, or quality of the containing object expressed as a namespace qualified name/value pair.
   *
   * @param value
   *           the prop value to set
   */
  public void setProps(@NonNull List<Property> value) {
    _props = value;
  }

  /**
   * Add a new {@link Property} item to the underlying collection.
   * @param item the item to add
   * @return {@code true}
   */
  public boolean addProp(Property item) {
    Property value = ObjectUtils.requireNonNull(item,"item cannot be null");
    if (_props == null) {
      _props = new LinkedList<>();
    }
    return _props.add(value);
  }

  /**
   * Remove the first matching {@link Property} item from the underlying collection.
   * @param item the item to remove
   * @return {@code true} if the item was removed or {@code false} otherwise
   */
  public boolean removeProp(Property item) {
    Property value = ObjectUtils.requireNonNull(item,"item cannot be null");
    return _props != null && _props.remove(value);
  }

  /**
   * Get the "{@literal Link}".
   *
   * <p>
   * A reference to a local or remote resource, that has a specific relation to the containing object.
   *
   * @return the link value
   */
  @NonNull
  public List<Link> getLinks() {
    if (_links == null) {
      _links = new LinkedList<>();
    }
    return ObjectUtils.notNull(_links);
  }

  /**
   * Set the "{@literal Link}".
   *
   * <p>
   * A reference to a local or remote resource, that has a specific relation to the containing object.
   *
   * @param value
   *           the link value to set
   */
  public void setLinks(@NonNull List<Link> value) {
    _links = value;
  }

  /**
   * Add a new {@link Link} item to the underlying collection.
   * @param item the item to add
   * @return {@code true}
   */
  public boolean addLink(Link item) {
    Link value = ObjectUtils.requireNonNull(item,"item cannot be null");
    if (_links == null) {
      _links = new LinkedList<>();
    }
    return _links.add(value);
  }

  /**
   * Remove the first matching {@link Link} item from the underlying collection.
   * @param item the item to remove
   * @return {@code true} if the item was removed or {@code false} otherwise
   */
  public boolean removeLink(Link item) {
    Link value = ObjectUtils.requireNonNull(item,"item cannot be null");
    return _links != null && _links.remove(value);
  }

  /**
   * Get the "{@literal Remarks}".
   *
   * <p>
   * Additional commentary about the containing object.
   *
   * @return the remarks value, or {@code null} if not set
   */
  @Nullable
  public MarkupMultiline getRemarks() {
    return _remarks;
  }

  /**
   * Set the "{@literal Remarks}".
   *
   * <p>
   * Additional commentary about the containing object.
   *
   * @param value
   *           the remarks value to set, or {@code null} to clear
   */
  public void setRemarks(@Nullable MarkupMultiline value) {
    _remarks = value;
  }

  @Override
  public String toString() {
    return ObjectUtils.notNull(new ReflectionToStringBuilder(this, ToStringStyle.MULTI_LINE_STYLE).toString());
  }
}