001package gov.nist.secauto.oscal.lib.model;
002
003import gov.nist.secauto.metaschema.binding.model.annotations.BoundAssembly;
004import gov.nist.secauto.metaschema.binding.model.annotations.BoundField;
005import gov.nist.secauto.metaschema.binding.model.annotations.BoundFieldValue;
006import gov.nist.secauto.metaschema.binding.model.annotations.BoundFlag;
007import gov.nist.secauto.metaschema.binding.model.annotations.Expect;
008import gov.nist.secauto.metaschema.binding.model.annotations.GroupAs;
009import gov.nist.secauto.metaschema.binding.model.annotations.MetaschemaAssembly;
010import gov.nist.secauto.metaschema.binding.model.annotations.ValueConstraints;
011import gov.nist.secauto.metaschema.model.common.JsonGroupAsBehavior;
012import gov.nist.secauto.metaschema.model.common.constraint.IConstraint;
013import gov.nist.secauto.metaschema.model.common.datatype.adapter.StringAdapter;
014import gov.nist.secauto.metaschema.model.common.datatype.adapter.UuidAdapter;
015import gov.nist.secauto.metaschema.model.common.datatype.markup.MarkupLine;
016import gov.nist.secauto.metaschema.model.common.datatype.markup.MarkupLineAdapter;
017import gov.nist.secauto.metaschema.model.common.util.ObjectUtils;
018import java.lang.Override;
019import java.lang.String;
020import java.util.LinkedList;
021import java.util.List;
022import java.util.UUID;
023import org.apache.commons.lang3.builder.MultilineRecursiveToStringStyle;
024import org.apache.commons.lang3.builder.ReflectionToStringBuilder;
025
026/**
027 * Information about the protocol used to provide a service.
028 */
029@MetaschemaAssembly(
030    formalName = "Service Protocol Information",
031    description = "Information about the protocol used to provide a service.",
032    name = "protocol",
033    metaschema = OscalImplementationCommonMetaschema.class
034)
035@ValueConstraints(
036    expect = @Expect(level = IConstraint.Level.WARNING, test = "@uuid", message = "It is a best practice to provide a UUID.")
037)
038public class Protocol {
039  @BoundFlag(
040      formalName = "Service Protocol Information Universally Unique Identifier",
041      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.",
042      useName = "uuid",
043      typeAdapter = UuidAdapter.class
044  )
045  private UUID _uuid;
046
047  @BoundFlag(
048      formalName = "Protocol Name",
049      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).",
050      useName = "name",
051      required = true,
052      typeAdapter = StringAdapter.class,
053      remarks = "The short name of the protocol (e.g., https)."
054  )
055  private String _name;
056
057  /**
058   * "A human readable name for the protocol (e.g., Transport Layer Security)."
059   */
060  @BoundField(
061      formalName = "Protocol Title",
062      description = "A human readable name for the protocol (e.g., Transport Layer Security).",
063      useName = "title"
064  )
065  @BoundFieldValue(
066      typeAdapter = MarkupLineAdapter.class
067  )
068  private MarkupLine _title;
069
070  @BoundAssembly(
071      formalName = "Port Range",
072      description = "Where applicable this is the IPv4 port range on which the service operates.",
073      useName = "port-range",
074      maxOccurs = -1
075  )
076  @GroupAs(
077      name = "port-ranges",
078      inJson = JsonGroupAsBehavior.LIST
079  )
080  private List<PortRange> _portRanges;
081
082  public Protocol() {
083  }
084
085  public UUID getUuid() {
086    return _uuid;
087  }
088
089  public void setUuid(UUID value) {
090    _uuid = value;
091  }
092
093  public String getName() {
094    return _name;
095  }
096
097  public void setName(String value) {
098    _name = value;
099  }
100
101  public MarkupLine getTitle() {
102    return _title;
103  }
104
105  public void setTitle(MarkupLine value) {
106    _title = value;
107  }
108
109  public List<PortRange> getPortRanges() {
110    return _portRanges;
111  }
112
113  public void setPortRanges(List<PortRange> value) {
114    _portRanges = value;
115  }
116
117  /**
118   * Add a new {@link PortRange} item to the underlying collection.
119   * @param item the item to add
120   * @return {@code true}
121   */
122  public boolean addPortRange(PortRange item) {
123    PortRange value = ObjectUtils.requireNonNull(item,"item cannot be null");
124    if (_portRanges == null) {
125      _portRanges = new LinkedList<>();
126    }
127    return _portRanges.add(value);
128  }
129
130  /**
131   * Remove the first matching {@link PortRange} item from the underlying collection.
132   * @param item the item to remove
133   * @return {@code true} if the item was removed or {@code false} otherwise
134   */
135  public boolean removePortRange(PortRange item) {
136    PortRange value = ObjectUtils.requireNonNull(item,"item cannot be null");
137    return _portRanges == null ? false : _portRanges.remove(value);
138  }
139
140  @Override
141  public String toString() {
142    return new ReflectionToStringBuilder(this, MultilineRecursiveToStringStyle.MULTI_LINE_STYLE).toString();
143  }
144}