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

import dev.metaschema.core.datatype.adapter.TokenAdapter;
import dev.metaschema.core.datatype.adapter.UriAdapter;
import dev.metaschema.core.datatype.markup.MarkupLine;
import dev.metaschema.core.datatype.markup.MarkupLineAdapter;
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 dev.metaschema.oscal.lib.model.control.AbstractPart;
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 org.apache.commons.lang3.builder.ReflectionToStringBuilder;
import org.apache.commons.lang3.builder.ToStringStyle;

/**
 * An annotated, markup-based textual element of a control's or catalog group's definition, or a child of another part.
 */
@MetaschemaAssembly(
    formalName = "Part",
    description = "An annotated, markup-based textual element of a control's or catalog group's definition, or a child of another part.",
    name = "part",
    moduleClass = OscalControlCommonModule.class,
    remarks = "A `part` provides for logical partitioning of prose, and can be thought of as a grouping structure (e.g., section). A `part` can have child parts allowing for arbitrary nesting of prose content (e.g., statement hierarchy). A `part` can contain `prop` objects that allow for enriching prose text with structured name/value information.\n"
            + "\n"
            + "A `part` can be assigned an optional `id`, which allows references to this part from within a catalog, or within an instance of another OSCAL model that has a need to reference the part. Examples of where part referencing is used in OSCAL include:\n"
            + "\n"
            + "- Referencing a part by id to tailor (make modifications to) a control statement in a profile.\n"
            + "- Referencing a control statement represented by a part in a system security plan implemented-requirement where a statement-level response is desired.\n"
            + "\n"
            + "Use of `part` and `prop` provides for a wide degree of extensibility within the OSCAL catalog model. The optional `ns` provides a means to qualify a part's `name`, allowing for organization-specific vocabularies to be defined with clear semantics. Any organization that extends OSCAL in this way should consistently assign a `ns` value that represents the organization, making a given namespace qualified `name` unique to that organization. This allows the combination of `ns` and `name` to always be unique and unambiguous, even when mixed with extensions from other organizations. Each organization is responsible for governance of their own extensions, and is strongly encouraged to publish their extensions as standards to their user community. If no `ns` is provided, the name is expected to be in the \"OSCAL\" namespace.\n"
            + "\n"
            + "To ensure a `ns` is unique to an organization and naming conflicts are avoided, a URI containing a DNS or other globally defined organization name should be used. For example, if FedRAMP and DoD both extend OSCAL, FedRAMP will use the `ns` `http://fedramp.gov/ns/oscal`, while DoD might use the `ns` `https://defense.gov` for any organization specific `name`.\n"
            + "\n"
            + "Tools that process OSCAL content are not required to interpret unrecognized OSCAL extensions; however, OSCAL compliant tools should not modify or remove unrecognized extensions, unless there is a compelling reason to do so, such as data sensitivity.",
    valueConstraints = @ValueConstraints(allowedValues = @AllowedValues(id = "oscal-part-prop-name", level = IConstraint.Level.ERROR, target = "prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name", values = {@AllowedValue(value = "label", description = "A human-readable label for the parent context, which may be rendered in place of the actual identifier for some use cases."), @AllowedValue(value = "sort-id", description = "An alternative identifier, whose value is easily sortable among other such values in the document."), @AllowedValue(value = "alt-identifier", description = "An alternate or aliased identifier for the parent context.")}))
)
public class ControlPart extends AbstractPart implements IBoundObject {
  private final IMetaschemaData __metaschemaData;

  /**
   * A unique identifier for the part.
   */
  @BoundFlag(
      formalName = "Part Identifier",
      description = "A unique identifier for the part.",
      name = "id",
      typeAdapter = TokenAdapter.class,
      remarks = "While a part is not required to have an id, it is often desirable for an identifier to be provided, which allows the part to be referenced elsewhere in OSCAL document instances. For this reason, it is RECOMMENDED to provide a part identifier."
  )
  private String _id;

  /**
   * A textual label that uniquely identifies the part's semantic type, which exists in a value space qualified by the <code>ns</code>.
   */
  @BoundFlag(
      formalName = "Part Name",
      description = "A textual label that uniquely identifies the part's semantic type, which exists in a value space qualified by the `ns`.",
      name = "name",
      required = true,
      typeAdapter = TokenAdapter.class
  )
  private String _name;

  /**
   * An optional namespace qualifying the part's <code>name</code>. This allows different organizations to associate distinct semantics with the same name.
   */
  @BoundFlag(
      formalName = "Part Namespace",
      description = "An optional namespace qualifying the part's `name`. This allows different organizations to associate distinct semantics 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;

  /**
   * An optional textual providing a sub-type or characterization of the part's <code>name</code>, or a category to which the part belongs.
   */
  @BoundFlag(
      formalName = "Part Class",
      description = "An optional textual providing a sub-type or characterization of the part's `name`, or a category to which the part belongs.",
      name = "class",
      typeAdapter = TokenAdapter.class,
      remarks = "One use of this flag is to distinguish or discriminate between the semantics of multiple parts of the same control with the same `name` and `ns` (since even within a given namespace it can be useful to overload a name).\n"
              + "\n"
              + "A `class` can be used in validation rules to express extra constraints over named items of a specific `class` value.\n"
              + "\n"
              + "A `class` can also be used in an OSCAL profile as a means to target an alteration to control content."
  )
  private String _clazz;

  /**
   * An optional name given to the part, which may be used by a tool for display and navigation.
   */
  @BoundField(
      formalName = "Part Title",
      description = "An optional name given to the part, which may be used by a tool for display and navigation.",
      useName = "title",
      typeAdapter = MarkupLineAdapter.class
  )
  private MarkupLine _title;

  /**
   * 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;

  /**
   * Permits multiple paragraphs, lists, tables etc.
   */
  @BoundField(
      formalName = "Part Text",
      description = "Permits multiple paragraphs, lists, tables etc.",
      useName = "prose",
      inXmlWrapped = false,
      typeAdapter = MarkupMultilineAdapter.class
  )
  private MarkupMultiline _prose;

  /**
   * An annotated, markup-based textual element of a control's or catalog group's definition, or a child of another part.
   */
  @BoundAssembly(
      formalName = "Part",
      description = "An annotated, markup-based textual element of a control's or catalog group's definition, or a child of another part.",
      useName = "part",
      maxOccurs = -1,
      groupAs = @GroupAs(name = "parts", inJson = JsonGroupAsBehavior.LIST)
  )
  private List<ControlPart> _parts;

  /**
   * 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;

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

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

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

  /**
   * Get the "{@literal Part Identifier}".
   *
   * <p>
   * A unique identifier for the part.
   *
   * @return the id value, or {@code null} if not set
   */
  @Nullable
  public String getId() {
    return _id;
  }

  /**
   * Set the "{@literal Part Identifier}".
   *
   * <p>
   * A unique identifier for the part.
   *
   * @param value
   *           the id value to set, or {@code null} to clear
   */
  public void setId(@Nullable String value) {
    _id = value;
  }

  /**
   * Get the "{@literal Part Name}".
   *
   * <p>
   * A textual label that uniquely identifies the part's semantic type, which exists in a value space qualified by the <code>ns</code>.
   *
   * @return the name value
   */
  @NonNull
  public String getName() {
    return _name;
  }

  /**
   * Set the "{@literal Part Name}".
   *
   * <p>
   * A textual label that uniquely identifies the part's semantic type, which exists in a value space qualified by the <code>ns</code>.
   *
   * @param value
   *           the name value to set
   */
  public void setName(@NonNull String value) {
    _name = value;
  }

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

  /**
   * Set the "{@literal Part Namespace}".
   *
   * <p>
   * An optional namespace qualifying the part's <code>name</code>. This allows different organizations to associate distinct semantics 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 Part Class}".
   *
   * <p>
   * An optional textual providing a sub-type or characterization of the part's <code>name</code>, or a category to which the part belongs.
   *
   * @return the class value, or {@code null} if not set
   */
  @Nullable
  public String getClazz() {
    return _clazz;
  }

  /**
   * Set the "{@literal Part Class}".
   *
   * <p>
   * An optional textual providing a sub-type or characterization of the part's <code>name</code>, or a category to which the part belongs.
   *
   * @param value
   *           the class value to set, or {@code null} to clear
   */
  public void setClazz(@Nullable String value) {
    _clazz = value;
  }

  /**
   * Get the "{@literal Part Title}".
   *
   * <p>
   * An optional name given to the part, which may be used by a tool for display and navigation.
   *
   * @return the title value, or {@code null} if not set
   */
  @Nullable
  public MarkupLine getTitle() {
    return _title;
  }

  /**
   * Set the "{@literal Part Title}".
   *
   * <p>
   * An optional name given to the part, which may be used by a tool for display and navigation.
   *
   * @param value
   *           the title value to set, or {@code null} to clear
   */
  public void setTitle(@Nullable MarkupLine value) {
    _title = 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 Part Text}".
   *
   * <p>
   * Permits multiple paragraphs, lists, tables etc.
   *
   * @return the prose value, or {@code null} if not set
   */
  @Nullable
  public MarkupMultiline getProse() {
    return _prose;
  }

  /**
   * Set the "{@literal Part Text}".
   *
   * <p>
   * Permits multiple paragraphs, lists, tables etc.
   *
   * @param value
   *           the prose value to set, or {@code null} to clear
   */
  public void setProse(@Nullable MarkupMultiline value) {
    _prose = value;
  }

  /**
   * Get the "{@literal Part}".
   *
   * <p>
   * An annotated, markup-based textual element of a control's or catalog group's definition, or a child of another part.
   *
   * @return the part value
   */
  @NonNull
  public List<ControlPart> getParts() {
    if (_parts == null) {
      _parts = new LinkedList<>();
    }
    return ObjectUtils.notNull(_parts);
  }

  /**
   * Set the "{@literal Part}".
   *
   * <p>
   * An annotated, markup-based textual element of a control's or catalog group's definition, or a child of another part.
   *
   * @param value
   *           the part value to set
   */
  public void setParts(@NonNull List<ControlPart> value) {
    _parts = value;
  }

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

  /**
   * Remove the first matching {@link ControlPart} 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 removePart(ControlPart item) {
    ControlPart value = ObjectUtils.requireNonNull(item,"item cannot be null");
    return _parts != null && _parts.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);
  }

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