001package gov.nist.secauto.oscal.lib.model;
002
003import gov.nist.secauto.metaschema.core.datatype.adapter.StringAdapter;
004import gov.nist.secauto.metaschema.core.datatype.adapter.UuidAdapter;
005import gov.nist.secauto.metaschema.core.datatype.markup.MarkupLine;
006import gov.nist.secauto.metaschema.core.datatype.markup.MarkupLineAdapter;
007import gov.nist.secauto.metaschema.core.model.IBoundObject;
008import gov.nist.secauto.metaschema.core.model.IMetaschemaData;
009import gov.nist.secauto.metaschema.core.model.JsonGroupAsBehavior;
010import gov.nist.secauto.metaschema.core.model.constraint.IConstraint;
011import gov.nist.secauto.metaschema.core.util.ObjectUtils;
012import gov.nist.secauto.metaschema.databind.model.annotations.BoundAssembly;
013import gov.nist.secauto.metaschema.databind.model.annotations.BoundField;
014import gov.nist.secauto.metaschema.databind.model.annotations.BoundFlag;
015import gov.nist.secauto.metaschema.databind.model.annotations.Expect;
016import gov.nist.secauto.metaschema.databind.model.annotations.GroupAs;
017import gov.nist.secauto.metaschema.databind.model.annotations.MetaschemaAssembly;
018import gov.nist.secauto.metaschema.databind.model.annotations.ValueConstraints;
019import java.lang.Override;
020import java.lang.String;
021import java.util.LinkedList;
022import java.util.List;
023import java.util.UUID;
024import org.apache.commons.lang3.builder.ReflectionToStringBuilder;
025import org.apache.commons.lang3.builder.ToStringStyle;
026
027/**
028 * Information about the protocol used to provide a service.
029 */
030@MetaschemaAssembly(
031    formalName = "Service Protocol Information",
032    description = "Information about the protocol used to provide a service.",
033    name = "protocol",
034    moduleClass = OscalImplementationCommonModule.class,
035    valueConstraints = @ValueConstraints(expect = @Expect(level = IConstraint.Level.WARNING, test = "@uuid", message = "It is a best practice to provide a UUID."))
036)
037public class Protocol implements IBoundObject {
038  private final IMetaschemaData __metaschemaData;
039
040  /**
041   * "A <a href=\"https://pages.nist.gov/OSCAL/concepts/identifier-use/#machine-oriented\">machine-oriented</a>, <a href=\"https://pages.nist.gov/OSCAL/concepts/identifier-use/#globally-unique\">globally unique</a> identifier with <a href=\"https://pages.nist.gov/OSCAL/concepts/identifier-use/#cross-instance\">cross-instance</a> scope that can be used to reference this service protocol information elsewhere in <a href=\"https://pages.nist.gov/OSCAL/concepts/identifier-use/#scope\">this or other OSCAL instances</a>. The locally defined <em>UUID</em> of the <code>service protocol</code> can be used to reference the data item locally or globally (e.g., in an imported OSCAL instance). This UUID should be assigned <a href=\"https://pages.nist.gov/OSCAL/concepts/identifier-use/#consistency\">per-subject</a>, which means it should be consistently used to identify the same subject across revisions of the document."
042   */
043  @BoundFlag(
044      formalName = "Service Protocol Information Universally Unique Identifier",
045      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.",
046      name = "uuid",
047      typeAdapter = UuidAdapter.class
048  )
049  private UUID _uuid;
050
051  /**
052   * "The common name of the protocol, which should be the appropriate &quot;service name&quot; from the <a href=\"https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml\">IANA Service Name and Transport Protocol Port Number Registry</a>."
053   */
054  @BoundFlag(
055      formalName = "Protocol Name",
056      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).",
057      name = "name",
058      typeAdapter = StringAdapter.class,
059      remarks = "The short name of the protocol (e.g., https)."
060  )
061  private String _name;
062
063  @BoundField(
064      formalName = "Protocol Title",
065      description = "A human readable name for the protocol (e.g., Transport Layer Security).",
066      useName = "title",
067      typeAdapter = MarkupLineAdapter.class
068  )
069  private MarkupLine _title;
070
071  @BoundAssembly(
072      formalName = "Port Range",
073      description = "Where applicable this is the transport layer protocol port range an IPv4-based or IPv6-based service uses.",
074      useName = "port-range",
075      maxOccurs = -1,
076      groupAs = @GroupAs(name = "port-ranges", inJson = JsonGroupAsBehavior.LIST)
077  )
078  private List<PortRange> _portRanges;
079
080  public Protocol() {
081    this(null);
082  }
083
084  public Protocol(IMetaschemaData data) {
085    this.__metaschemaData = data;
086  }
087
088  @Override
089  public IMetaschemaData getMetaschemaData() {
090    return __metaschemaData;
091  }
092
093  public UUID getUuid() {
094    return _uuid;
095  }
096
097  public void setUuid(UUID value) {
098    _uuid = value;
099  }
100
101  public String getName() {
102    return _name;
103  }
104
105  public void setName(String value) {
106    _name = value;
107  }
108
109  public MarkupLine getTitle() {
110    return _title;
111  }
112
113  public void setTitle(MarkupLine value) {
114    _title = value;
115  }
116
117  public List<PortRange> getPortRanges() {
118    return _portRanges;
119  }
120
121  public void setPortRanges(List<PortRange> value) {
122    _portRanges = value;
123  }
124
125  /**
126   * Add a new {@link PortRange} item to the underlying collection.
127   * @param item the item to add
128   * @return {@code true}
129   */
130  public boolean addPortRange(PortRange item) {
131    PortRange value = ObjectUtils.requireNonNull(item,"item cannot be null");
132    if (_portRanges == null) {
133      _portRanges = new LinkedList<>();
134    }
135    return _portRanges.add(value);
136  }
137
138  /**
139   * Remove the first matching {@link PortRange} item from the underlying collection.
140   * @param item the item to remove
141   * @return {@code true} if the item was removed or {@code false} otherwise
142   */
143  public boolean removePortRange(PortRange item) {
144    PortRange value = ObjectUtils.requireNonNull(item,"item cannot be null");
145    return _portRanges != null && _portRanges.remove(value);
146  }
147
148  @Override
149  public String toString() {
150    return new ReflectionToStringBuilder(this, ToStringStyle.MULTI_LINE_STYLE).toString();
151  }
152}