Protocol.java

package gov.nist.secauto.oscal.lib.model;

import gov.nist.secauto.metaschema.binding.model.annotations.BoundAssembly;
import gov.nist.secauto.metaschema.binding.model.annotations.BoundField;
import gov.nist.secauto.metaschema.binding.model.annotations.BoundFieldValue;
import gov.nist.secauto.metaschema.binding.model.annotations.BoundFlag;
import gov.nist.secauto.metaschema.binding.model.annotations.Expect;
import gov.nist.secauto.metaschema.binding.model.annotations.GroupAs;
import gov.nist.secauto.metaschema.binding.model.annotations.MetaschemaAssembly;
import gov.nist.secauto.metaschema.binding.model.annotations.ValueConstraints;
import gov.nist.secauto.metaschema.model.common.JsonGroupAsBehavior;
import gov.nist.secauto.metaschema.model.common.constraint.IConstraint;
import gov.nist.secauto.metaschema.model.common.datatype.adapter.StringAdapter;
import gov.nist.secauto.metaschema.model.common.datatype.adapter.UuidAdapter;
import gov.nist.secauto.metaschema.model.common.datatype.markup.MarkupLine;
import gov.nist.secauto.metaschema.model.common.datatype.markup.MarkupLineAdapter;
import gov.nist.secauto.metaschema.model.common.util.ObjectUtils;
import java.lang.Override;
import java.lang.String;
import java.util.LinkedList;
import java.util.List;
import java.util.UUID;
import org.apache.commons.lang3.builder.MultilineRecursiveToStringStyle;
import org.apache.commons.lang3.builder.ReflectionToStringBuilder;

/**
 * Information about the protocol used to provide a service.
 */
@MetaschemaAssembly(
    formalName = "Service Protocol Information",
    description = "Information about the protocol used to provide a service.",
    name = "protocol",
    metaschema = OscalImplementationCommonMetaschema.class
)
@ValueConstraints(
    expect = @Expect(level = IConstraint.Level.WARNING, test = "@uuid", message = "It is a best practice to provide a UUID.")
)
public class Protocol {
  @BoundFlag(
      formalName = "Service Protocol Information Universally Unique Identifier",
      description = "A [machine-oriented](https://pages.nist.gov/OSCAL/concepts/identifier-use/#machine-oriented), [globally unique](https://pages.nist.gov/OSCAL/concepts/identifier-use/#globally-unique) identifier with [cross-instance](https://pages.nist.gov/OSCAL/concepts/identifier-use/#cross-instance) scope that can be used to reference this service protocol information elsewhere in [this or other OSCAL instances](https://pages.nist.gov/OSCAL/concepts/identifier-use/#scope). The locally defined *UUID* of the `service protocol` can be used to reference the data item locally or globally (e.g., in an imported OSCAL instance). This UUID should be assigned [per-subject](https://pages.nist.gov/OSCAL/concepts/identifier-use/#consistency), which means it should be consistently used to identify the same subject across revisions of the document.",
      useName = "uuid",
      typeAdapter = UuidAdapter.class
  )
  private UUID _uuid;

  @BoundFlag(
      formalName = "Protocol Name",
      description = "The common name of the protocol, which should be the appropriate \"service name\" from the [IANA Service Name and Transport Protocol Port Number Registry](https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml).",
      useName = "name",
      required = true,
      typeAdapter = StringAdapter.class,
      remarks = "The short name of the protocol (e.g., https)."
  )
  private String _name;

  /**
   * "A human readable name for the protocol (e.g., Transport Layer Security)."
   */
  @BoundField(
      formalName = "Protocol Title",
      description = "A human readable name for the protocol (e.g., Transport Layer Security).",
      useName = "title"
  )
  @BoundFieldValue(
      typeAdapter = MarkupLineAdapter.class
  )
  private MarkupLine _title;

  @BoundAssembly(
      formalName = "Port Range",
      description = "Where applicable this is the IPv4 port range on which the service operates.",
      useName = "port-range",
      maxOccurs = -1
  )
  @GroupAs(
      name = "port-ranges",
      inJson = JsonGroupAsBehavior.LIST
  )
  private List<PortRange> _portRanges;

  public Protocol() {
  }

  public UUID getUuid() {
    return _uuid;
  }

  public void setUuid(UUID value) {
    _uuid = value;
  }

  public String getName() {
    return _name;
  }

  public void setName(String value) {
    _name = value;
  }

  public MarkupLine getTitle() {
    return _title;
  }

  public void setTitle(MarkupLine value) {
    _title = value;
  }

  public List<PortRange> getPortRanges() {
    return _portRanges;
  }

  public void setPortRanges(List<PortRange> value) {
    _portRanges = value;
  }

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

  /**
   * Remove the first matching {@link PortRange} 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 removePortRange(PortRange item) {
    PortRange value = ObjectUtils.requireNonNull(item,"item cannot be null");
    return _portRanges == null ? false : _portRanges.remove(value);
  }

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