// 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.StringAdapter;
import dev.metaschema.core.datatype.adapter.TokenAdapter;
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.BoundChoice;
import dev.metaschema.databind.model.annotations.BoundField;
import dev.metaschema.databind.model.annotations.BoundFlag;
import dev.metaschema.databind.model.annotations.Expect;
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.AbstractParameter;
import edu.umd.cs.findbugs.annotations.NonNull;
import edu.umd.cs.findbugs.annotations.Nullable;
import java.util.LinkedList;
import java.util.List;
import org.apache.commons.lang3.builder.ReflectionToStringBuilder;
import org.apache.commons.lang3.builder.ToStringStyle;

/**
 * Parameters provide a mechanism for the dynamic assignment of value(s) in a control.
 */
@MetaschemaAssembly(
    formalName = "Parameter",
    description = "Parameters provide a mechanism for the dynamic assignment of value(s) in a control.",
    name = "parameter",
    moduleClass = OscalControlCommonModule.class,
    remarks = "In a catalog, a parameter is typically used as a placeholder for the future assignment of a parameter value, although the OSCAL model allows for the direct assignment of a value if desired by the control author. The `value` may be optionally used to specify one or more values. If no value is provided, then it is expected that the value will be provided at the Profile or Implementation layer.\n"
            + "\n"
            + "A parameter can include a variety of metadata options that support the future solicitation of one or more values. A `label` provides a textual placeholder that can be used in a tool to solicit parameter value input, or to display in catalog documentation. The `desc` provides a short description of what the parameter is used for, which can be used in tooling to help a user understand how to use the parameter. A `constraint` can be used to provide criteria for the allowed values. A `guideline` provides a recommendation for the use of a parameter.",
    valueConstraints = @ValueConstraints(allowedValues = {@AllowedValues(id = "oscal-parameter-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."), @AllowedValue(value = "alt-label", description = "An alternate to the value provided by the parameter's label. This will typically be qualified by a class.")}), @AllowedValues(id = "oscal-rmf-parameter-prop-name", level = IConstraint.Level.ERROR, target = "prop[has-oscal-namespace('http://csrc.nist.gov/ns/rmf')]/@name", values = @AllowedValue(value = "aggregates", description = "The parent parameter provides an aggregation of two or more other parameters, each described by this property."))}, expect = @Expect(id = "oscal-parameter-depends-on-deprecated", level = IConstraint.Level.ERROR, test = "not(exists(@depends-on))", message = "depends-on is deprecated"))
)
public class Parameter extends AbstractParameter implements IBoundObject {
  private final IMetaschemaData __metaschemaData;

  /**
   * A unique identifier for the parameter.
   */
  @BoundFlag(
      formalName = "Parameter Identifier",
      description = "A unique identifier for the parameter.",
      name = "id",
      required = true,
      typeAdapter = TokenAdapter.class
  )
  private String _id;

  /**
   * A textual label that provides a characterization of the type, purpose, use or scope of the parameter.
   */
  @BoundFlag(
      formalName = "Parameter Class",
      description = "A textual label that provides a characterization of the type, purpose, use or scope of the parameter.",
      name = "class",
      typeAdapter = TokenAdapter.class,
      remarks = "A `class` can be used in validation rules to express extra constraints over named items of a specific `class` value."
  )
  private String _clazz;

  /**
   * <strong>(deprecated)</strong> Another parameter invoking this one. This construct has been deprecated and should not be used.
   */
  @BoundFlag(
      formalName = "Depends on",
      description = "**(deprecated)** Another parameter invoking this one. This construct has been deprecated and should not be used.",
      name = "depends-on",
      typeAdapter = TokenAdapter.class
  )
  private String _dependsOn;

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

  /**
   * A short, placeholder name for the parameter, which can be used as a substitute for a <code>value</code> if no value is assigned.
   */
  @BoundField(
      formalName = "Parameter Label",
      description = "A short, placeholder name for the parameter, which can be used as a substitute for a `value` if no value is assigned.",
      useName = "label",
      remarks = "The label value is intended use when rendering a parameter in generated documentation or a user interface when a parameter is referenced. Note that labels are not required to be distinctive, which means that parameters within the same control may have the same label.",
      typeAdapter = MarkupLineAdapter.class
  )
  private MarkupLine _label;

  /**
   * Describes the purpose and use of a parameter.
   */
  @BoundField(
      formalName = "Parameter Usage Description",
      description = "Describes the purpose and use of a parameter.",
      useName = "usage",
      typeAdapter = MarkupMultilineAdapter.class
  )
  private MarkupMultiline _usage;

  /**
   * A formal or informal expression of a constraint or test.
   */
  @BoundAssembly(
      formalName = "Constraint",
      description = "A formal or informal expression of a constraint or test.",
      useName = "constraint",
      maxOccurs = -1,
      groupAs = @GroupAs(name = "constraints", inJson = JsonGroupAsBehavior.LIST)
  )
  private List<ParameterConstraint> _constraints;

  /**
   * A prose statement that provides a recommendation for the use of a parameter.
   */
  @BoundAssembly(
      formalName = "Guideline",
      description = "A prose statement that provides a recommendation for the use of a parameter.",
      useName = "guideline",
      maxOccurs = -1,
      groupAs = @GroupAs(name = "guidelines", inJson = JsonGroupAsBehavior.LIST)
  )
  private List<ParameterGuideline> _guidelines;

  /**
   * A parameter value or set of values.
   */
  @BoundField(
      formalName = "Parameter Value",
      description = "A parameter value or set of values.",
      useName = "value",
      remarks = "A set of values provided in a catalog can be redefined in OSCAL's `profile` or `system-security-plan` models.",
      maxOccurs = -1,
      groupAs = @GroupAs(name = "values", inJson = JsonGroupAsBehavior.LIST),
      typeAdapter = StringAdapter.class
  )
  @BoundChoice(
      choiceId = "choice-1"
  )
  private List<String> _values;

  /**
   * Presenting a choice among alternatives.
   */
  @BoundAssembly(
      formalName = "Selection",
      description = "Presenting a choice among alternatives.",
      useName = "select",
      remarks = "The OSCAL parameter `value` construct can be used to prescribe a specific parameter value in a catalog or profile. In cases where a prescriptive value is not possible in a catalog or profile, it may be possible to constrain the set of possible values to a few options. Use of `select` in a parameter instead of `value` is a way of defining value options that **may** be set.\n"
              + "\n"
              + "A set of allowed parameter values expressed as a set of options which may be selected. These options constrain the permissible values that may be selected for the containing parameter. When the value assignment is made, such as in an OSCAL profile or system security plan, the actual selected value can be examined to determine if it matches one of the permissible choices for the parameter value.\n"
              + "\n"
              + "When the value of `how-many` is set to \"one-or-more\", multiple values may be assigned reflecting more than one choice."
  )
  @BoundChoice(
      choiceId = "choice-1"
  )
  private ParameterSelection _select;

  /**
   * 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.Parameter} instance with no metadata.
   */
  public Parameter() {
    this(null);
  }

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

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

  /**
   * Get the "{@literal Parameter Identifier}".
   *
   * <p>
   * A unique identifier for the parameter.
   *
   * @return the id value
   */
  @NonNull
  public String getId() {
    return _id;
  }

  /**
   * Set the "{@literal Parameter Identifier}".
   *
   * <p>
   * A unique identifier for the parameter.
   *
   * @param value
   *           the id value to set
   */
  public void setId(@NonNull String value) {
    _id = value;
  }

  /**
   * Get the "{@literal Parameter Class}".
   *
   * <p>
   * A textual label that provides a characterization of the type, purpose, use or scope of the parameter.
   *
   * @return the class value, or {@code null} if not set
   */
  @Nullable
  public String getClazz() {
    return _clazz;
  }

  /**
   * Set the "{@literal Parameter Class}".
   *
   * <p>
   * A textual label that provides a characterization of the type, purpose, use or scope of the parameter.
   *
   * @param value
   *           the class value to set, or {@code null} to clear
   */
  public void setClazz(@Nullable String value) {
    _clazz = value;
  }

  /**
   * Get the "{@literal Depends on}".
   *
   * <p>
   * <strong>(deprecated)</strong> Another parameter invoking this one. This construct has been deprecated and should not be used.
   *
   * @return the depends-on value, or {@code null} if not set
   */
  @Nullable
  public String getDependsOn() {
    return _dependsOn;
  }

  /**
   * Set the "{@literal Depends on}".
   *
   * <p>
   * <strong>(deprecated)</strong> Another parameter invoking this one. This construct has been deprecated and should not be used.
   *
   * @param value
   *           the depends-on value to set, or {@code null} to clear
   */
  public void setDependsOn(@Nullable String value) {
    _dependsOn = 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 Parameter Label}".
   *
   * <p>
   * A short, placeholder name for the parameter, which can be used as a substitute for a <code>value</code> if no value is assigned.
   *
   * @return the label value, or {@code null} if not set
   */
  @Nullable
  public MarkupLine getLabel() {
    return _label;
  }

  /**
   * Set the "{@literal Parameter Label}".
   *
   * <p>
   * A short, placeholder name for the parameter, which can be used as a substitute for a <code>value</code> if no value is assigned.
   *
   * @param value
   *           the label value to set, or {@code null} to clear
   */
  public void setLabel(@Nullable MarkupLine value) {
    _label = value;
  }

  /**
   * Get the "{@literal Parameter Usage Description}".
   *
   * <p>
   * Describes the purpose and use of a parameter.
   *
   * @return the usage value, or {@code null} if not set
   */
  @Nullable
  public MarkupMultiline getUsage() {
    return _usage;
  }

  /**
   * Set the "{@literal Parameter Usage Description}".
   *
   * <p>
   * Describes the purpose and use of a parameter.
   *
   * @param value
   *           the usage value to set, or {@code null} to clear
   */
  public void setUsage(@Nullable MarkupMultiline value) {
    _usage = value;
  }

  /**
   * Get the "{@literal Constraint}".
   *
   * <p>
   * A formal or informal expression of a constraint or test.
   *
   * @return the constraint value
   */
  @NonNull
  public List<ParameterConstraint> getConstraints() {
    if (_constraints == null) {
      _constraints = new LinkedList<>();
    }
    return ObjectUtils.notNull(_constraints);
  }

  /**
   * Set the "{@literal Constraint}".
   *
   * <p>
   * A formal or informal expression of a constraint or test.
   *
   * @param value
   *           the constraint value to set
   */
  public void setConstraints(@NonNull List<ParameterConstraint> value) {
    _constraints = value;
  }

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

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

  /**
   * Get the "{@literal Guideline}".
   *
   * <p>
   * A prose statement that provides a recommendation for the use of a parameter.
   *
   * @return the guideline value
   */
  @NonNull
  public List<ParameterGuideline> getGuidelines() {
    if (_guidelines == null) {
      _guidelines = new LinkedList<>();
    }
    return ObjectUtils.notNull(_guidelines);
  }

  /**
   * Set the "{@literal Guideline}".
   *
   * <p>
   * A prose statement that provides a recommendation for the use of a parameter.
   *
   * @param value
   *           the guideline value to set
   */
  public void setGuidelines(@NonNull List<ParameterGuideline> value) {
    _guidelines = value;
  }

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

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

  /**
   * Get the "{@literal Parameter Value}".
   *
   * <p>
   * A parameter value or set of values.
   *
   * @return the value value
   */
  @NonNull
  public List<String> getValues() {
    if (_values == null) {
      _values = new LinkedList<>();
    }
    return ObjectUtils.notNull(_values);
  }

  /**
   * Set the "{@literal Parameter Value}".
   *
   * <p>
   * A parameter value or set of values.
   *
   * @param value
   *           the value value to set
   */
  public void setValues(@NonNull List<String> value) {
    _values = value;
  }

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

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

  /**
   * Get the "{@literal Selection}".
   *
   * <p>
   * Presenting a choice among alternatives.
   *
   * @return the select value, or {@code null} if not set
   */
  @Nullable
  public ParameterSelection getSelect() {
    return _select;
  }

  /**
   * Set the "{@literal Selection}".
   *
   * <p>
   * Presenting a choice among alternatives.
   *
   * @param value
   *           the select value to set, or {@code null} to clear
   */
  public void setSelect(@Nullable ParameterSelection value) {
    _select = 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());
  }
}